From cb39847dee488c373dd5bc2a3706385342a59355 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Fri, 14 Aug 2020 18:31:01 +0200 Subject: [PATCH] Squashed 'docs/' changes from a26d0e610..7297c1172 7297c1172 Add note about caching for Hugo Pipes. c91be3403 minor markdown, capitalization and spelling fixes (#1183) fd4a103bf Fix several 404 errors (#1162) 69378bc20 Update related.md 28c24e95f Add note on setting baseURL 7b1502c99 minor typo fix (#1180) 33abeb4fe Update related.md 4887563f6 Update js.md ee5f1de2e Hugo 0.74.3 986ea0c8e releaser: Add release notes to /docs for release of 0.74.3 3299b44bd Fix Asciidoctor args bcb950347 resources/js: Add option for setting bundle format 3f8324918 resources/js: Add es5 build target git-subtree-dir: docs git-subtree-split: 7297c1172754078511ac1c10ca0dfd4cab629506 --- content/en/content-management/formats.md | 15 +++++------ .../image-processing/index.md | 2 +- content/en/content-management/page-bundles.md | 4 +-- content/en/content-management/related.md | 4 +-- .../content-management/syntax-highlighting.md | 5 ---- content/en/contribute/themes.md | 3 +-- content/en/functions/after.md | 2 +- .../deployment-with-wercker.md | 3 --- .../hosting-on-bitbucket.md | 6 ++--- .../hosting-on-gitlab.md | 4 +++ .../hosting-on-keycdn.md | 4 +-- content/en/hugo-pipes/introduction.md | 12 +++++++++ content/en/hugo-pipes/js.md | 7 ++++- content/en/news/0.74.3-relnotes/index.md | 26 +++++++++++++++++++ content/en/templates/internal.md | 2 +- content/en/variables/site.md | 2 +- netlify.toml | 8 +++--- 17 files changed, 72 insertions(+), 37 deletions(-) create mode 100644 content/en/news/0.74.3-relnotes/index.md diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md index f84d912ba..94d7e0f17 100644 --- a/content/en/content-management/formats.md +++ b/content/en/content-management/formats.md @@ -33,7 +33,7 @@ The current list of content formats in Hugo: | Blackfriday | blackfriday |Blackfriday will eventually be deprecated.| |MMark|mmark|Mmark is deprecated and will be removed in a future release.| |Emacs Org-Mode|org|See [go-org](https://github.com/niklasfasching/go-org).| -|AsciiDoc|asciidoc, adoc, ad|Needs AsciiDoc or [Asciidoctor][ascii] installed.| +|AsciiDoc|asciidocext, adoc, ad|Needs [Asciidoctor][ascii] installed.| |RST|rst|Needs [RST](http://docutils.sourceforge.net/rst.html) installed.| |Pandoc|pandoc, pdc|Needs [Pandoc](https://www.pandoc.org/) installed.| |HTML|html, htm|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.| @@ -44,17 +44,17 @@ The `markup identifier` is fetched from either the `markup` variable in front ma ## External Helpers Some of the formats in the table above needs external helpers installed on your PC. For example, for AsciiDoc files, -Hugo will try to call the `asciidoctor` or `asciidoc` command. This means that you will have to install the associated +Hugo will try to call the `asciidoctor` command. This means that you will have to install the associated tool on your machine to be able to use these formats. Hugo passes reasonable default arguments to these external helpers by default: -- `asciidoctor`: `--no-header-footer -v -` +- `asciidoctor`: `--no-header-footer --trace -` - `rst2html`: `--leave-comments --initial-header-level=2` - `pandoc`: `--mathjax` {{% warning "Performance of External Helpers" %}} -Because additional formats are external commands generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome. +Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome. {{% /warning %}} ### External Helper AsciiDoc @@ -74,14 +74,14 @@ Asciidoctor parameters can be customized in Hugo: Parameter | Default | Comment --- | --- | --- backend | `html5` | Don't change this unless you know what you are doing. -doctype | `article` | Document type (article, book or manpage). +doctype | `article` | Currently supported Document type is `article`. extensions | | Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, `asciidoctor-question`, `asciidoctor-rouge`. attributes | | Variables to be referenced in your `adoc` file. This is a list of variable name/value maps. See [Asciidoctor#attributes](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions). noheaderorfooter | true | Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Don't change this unless you know what you are doing. safemode | `unsafe` | Safe mode level `unsafe`, `safe`, `server` or `secure`. Don't change this unless you know what you are doing. sectionnumbers | `false` | Auto-number section titles. -verbose | `true` | Verbosely print processing information and configuration file checks to stderr. -trace | `false` | Include backtrace information on errors. +verbose | `false` | Verbosely print processing information and configuration file checks to stderr. +trace | `true` | Include backtrace information on errors. failurelevel | `fatal` | The minimum logging level that triggers a non-zero exit code (failure). workingfoldercurrent | `false` | Set the working folder to the rendered `adoc` file, so [include](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files) will work with relative paths. This setting uses the `asciidoctor` cli parameter `--base-dir` and attribute `outdir=`. For rendering [asciidoctor-diagram](https://asciidoctor.org/docs/asciidoctor-diagram/) `workingfoldercurrent` must be set to `true`. @@ -89,7 +89,6 @@ workingfoldercurrent | `false` | Set the working folder to the rendered `adoc` f [markup.asciidocext] extensions = ["asciidoctor-html5s", "asciidoctor-diagram"] workingFolderCurrent = true - trace = true [markup.asciidocext.attributes] my-base-url = "https://example.com/" my-attribute-name = "my value" diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index 745c2c53b..ebd3362dc 100644 --- a/content/en/content-management/image-processing/index.md +++ b/content/en/content-management/image-processing/index.md @@ -294,7 +294,7 @@ disableLatLong = false ## Smart Cropping of Images -By default, Hugo will use the [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the library author to improve this in the future. +By default, Hugo will use [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the library author to improve this in the future. An example using the sunset image from above: diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md index dc866445b..64b59194a 100644 --- a/content/en/content-management/page-bundles.md +++ b/content/en/content-management/page-bundles.md @@ -18,8 +18,8 @@ Page Bundles are a way to group [Page Resources](/content-management/page-resour A Page Bundle can be one of: -- Leaf Bundle (leaf means it has no children) -- Branch Bundle (home page, section, taxonomy terms, taxonomy list) +- Leaf Bundle (leaf means it has no children) +- Branch Bundle (home page, section, taxonomy terms, taxonomy list) | | Leaf Bundle | Branch Bundle | |-------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/content/en/content-management/related.md b/content/en/content-management/related.md index 8c18052fd..ce0cafa09 100644 --- a/content/en/content-management/related.md +++ b/content/en/content-management/related.md @@ -72,7 +72,7 @@ Hugo provides a sensible default configuration of Related Content, but you can f Without any `related` configuration set on the project, Hugo's Related Content methods will use the following. -```yaml +{{< code-toggle file="config" >}} related: threshold: 80 includeNewer: false @@ -82,7 +82,7 @@ related: weight: 100 - name: date weight: 10 -``` +{{< /code-toggle >}} Custom configuration should be set using the same syntax. diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md index c53a6d65e..0e5107f36 100644 --- a/content/en/content-management/syntax-highlighting.md +++ b/content/en/content-management/syntax-highlighting.md @@ -16,14 +16,12 @@ aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/] toc: true --- - Hugo uses [Chroma](https://github.com/alecthomas/chroma) as its code highlighter; it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments we used before. ## Configure Syntax Highlighter See [Configure Highlight](/getting-started/configuration-markup#highlight). - ## Generate Syntax Highlighter CSS If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet. @@ -36,7 +34,6 @@ hugo gen chromastyles --style=monokai > syntax.css Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles. - ## Highlight Shortcode Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting. @@ -80,8 +77,6 @@ func GetTitleFunc(style string) func(s string) string { } {{< / highlight >}} - - ## Highlight Template Func See [Highlight](/functions/highlight/). diff --git a/content/en/contribute/themes.md b/content/en/contribute/themes.md index 0fa7a68c1..fa22aedb2 100644 --- a/content/en/contribute/themes.md +++ b/content/en/contribute/themes.md @@ -24,9 +24,8 @@ A collection of all themes created by the Hugo community, including screenshots Another great site for Hugo themes is [jamstackthemes.dev/](https://jamstackthemes.dev/ssg/hugo/). - ### Add Your Theme to the Repo -In order to add your Hugo theme to [themes.gohugo.io] please [open up a new issue in the theme repository](https://github.com/gohugoio/hugoThemes/issues/new?template=theme-submission.md). **Please make sure that you've read the theme submission guidelines in the [README](https://github.com/gohugoio/hugoThemes/blob/master/README.md#adding-a-theme-to-the-list) of the hugoThemes repository.** +In order to add your Hugo theme to [themes.gohugo.io] please [open up a new issue in the theme repository](https://github.com/gohugoio/hugoThemes/issues/new?template=theme-submission.md). **Please make sure that you've read the theme submission guidelines in the [README](https://github.com/gohugoio/hugoThemes/blob/master/README.md#adding-a-theme-to-the-list) of the hugoThemes repository.** [themes.gohugo.io]: https://themes.gohugo.io/ diff --git a/content/en/functions/after.md b/content/en/functions/after.md index d627f792a..80c0dd241 100644 --- a/content/en/functions/after.md +++ b/content/en/functions/after.md @@ -62,5 +62,5 @@ You can use `after` in combination with the [`first` function][] and Hugo's [pow [`first` function]: /functions/first/ [list/section page]: /templates/section-templates/ -[lists]: /lists/ +[lists]: /templates/lists/#order-content [slice]: /functions/slice/ diff --git a/content/en/hosting-and-deployment/deployment-with-wercker.md b/content/en/hosting-and-deployment/deployment-with-wercker.md index 1fed46430..fcd0ea808 100644 --- a/content/en/hosting-and-deployment/deployment-with-wercker.md +++ b/content/en/hosting-and-deployment/deployment-with-wercker.md @@ -289,8 +289,6 @@ Once this workflow is established, you can update your website automatically by [The source code for the site used in this guide is available on GitHub][guidesource], as is the [Wercker Hugo Build step][guidestep]. -If you want to see an example of how you can deploy to S3 instead of GitHub pages, check [Wercker's documentation][werckerdocs] for guidance on setup. - [1]: /images/hosting-and-deployment/deployment-with-wercker/creating-a-basic-hugo-site.png [2]: /images/hosting-and-deployment/deployment-with-wercker/adding-the-project-to-github.png [3]: /images/hosting-and-deployment/deployment-with-wercker/wercker-sign-up.png @@ -321,4 +319,3 @@ If you want to see an example of how you can deploy to S3 instead of GitHub page [hugoconfig]: /getting-started/configuration/ [publicappurl]: https://app.wercker.com/#applications/5586dcbdaf7de9c51b02b0d5 [quickstart]: /getting-started/quick-start/ -[werckerdocs]: http://devcenter.wercker.com/docs/deploy/s3.html diff --git a/content/en/hosting-and-deployment/hosting-on-bitbucket.md b/content/en/hosting-and-deployment/hosting-on-bitbucket.md index 03710690e..9ab926751 100644 --- a/content/en/hosting-and-deployment/hosting-on-bitbucket.md +++ b/content/en/hosting-and-deployment/hosting-on-bitbucket.md @@ -56,11 +56,10 @@ In the rendered page response, the `https://__baseurl__` will be replaced with y We will now create a git repository and then push our code to Bitbucket. In Bitbucket, create a repository. -![][1] +![Bitbucket Screenshot][1] [1]: /images/hosting-and-deployment/hosting-on-bitbucket/bitbucket-create-repo.png - ``` # initialize new git repository git init @@ -133,11 +132,10 @@ Your code will be committed to Bitbucket, Bitbucket Pipelines will run your buil At this point, you can now create and edit blog posts directly in the Bitbucket UI. -![][2] +![Bitbucket blog Screenshot][2] [2]: /images/hosting-and-deployment/hosting-on-bitbucket/bitbucket-blog-post.png - ## Suggested next steps The code for this example can be found in this Bitbucket [repository](https://bitbucket.org/dundonian/hugo-docs-test). Aerobatic also provides a number of additional [plugins](https://www.aerobatic.com/docs) such as auth and redirects that you can use for your Hugo site. diff --git a/content/en/hosting-and-deployment/hosting-on-gitlab.md b/content/en/hosting-and-deployment/hosting-on-gitlab.md index eda592d43..0a40eb824 100644 --- a/content/en/hosting-and-deployment/hosting-on-gitlab.md +++ b/content/en/hosting-and-deployment/hosting-on-gitlab.md @@ -77,6 +77,10 @@ That's it! You can now follow the CI agent building your page at `https://gitlab After the build has passed, your new website is available at `https://.gitlab.io//`. +{{% note %}} +Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitLab pages repository if you're using the default GitLab Pages URL (e.g., `https://.gitlab.io//`) and not a custom domain. +{{% /note %}} + ## Next Steps GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/). diff --git a/content/en/hosting-and-deployment/hosting-on-keycdn.md b/content/en/hosting-and-deployment/hosting-on-keycdn.md index ca4ba219b..8d9cb0e63 100644 --- a/content/en/hosting-and-deployment/hosting-on-keycdn.md +++ b/content/en/hosting-and-deployment/hosting-on-keycdn.md @@ -66,7 +66,7 @@ pages: - master ``` -Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section. +Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section. The Secret Variable for your Zone ID should look similar to: @@ -89,6 +89,6 @@ git push -u origin master You can watch the progress and CI job output in your Gitlab project under “Pipelines”. -After verifying your CI job ran without issues, first check that your GitLab page shows up under `https://youruser.gitlab.io/reponame/` (it might look broken depending on your browser settings as all links point to your KeyCDN zone – don’t worry about that) and then by heading to whatever Zonealias / Zone URL you defined. +After verifying your CI job ran without issues, first check that your GitLab page shows up under `https://youruser.gitlab.io/reponame/` (it might look broken depending on your browser settings as all links point to your KeyCDN zone – don’t worry about that) and then by heading to whatever Zone alias / Zone URL you defined. To learn more about Hugo hosting options with KeyCDN, check out the complete [Hugo hosting with KeyCDN integration guide](https://www.keycdn.com/support/hugo-hosting/). diff --git a/content/en/hugo-pipes/introduction.md b/content/en/hugo-pipes/introduction.md index 439ff6c67..bd5bfdc4c 100755 --- a/content/en/hugo-pipes/introduction.md +++ b/content/en/hugo-pipes/introduction.md @@ -50,3 +50,15 @@ The example above can therefore also be written as follows: {{ $style := resources.Get "sass/main.scss" | toCSS | minify | fingerprint }} ``` + +### Caching + +Hugo Pipes invocations are cached based on the entire _pipe chain_. + +An example of a pipe chain is: + +```go-html-template +{{ $mainJs := resources.Get "js/main.js" | js.Build "main.js" | minify | fingerprint }} +``` + +The pipe chain is only invoked the first time it is encountered in a site build, and results are otherwise loaded from cache. As such, Hugo Pipes can be used in templates which are executed thousands or millions of times without negatively impacting the build performance. diff --git a/content/en/hugo-pipes/js.md b/content/en/hugo-pipes/js.md index b66778eb4..7f08e079c 100644 --- a/content/en/hugo-pipes/js.md +++ b/content/en/hugo-pipes/js.md @@ -28,7 +28,7 @@ minify [bool] target [string] : The language target. - One of: `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`. + One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`. Default is `esnext`. externals [slice] @@ -45,6 +45,11 @@ defines [map] {{ $defines := dict "process.env.NODE_ENV" `"development"` }} ``` +format [string] {{< new-in "0.74.3" >}} +: The output format. + One of: `iife`, `cjs`, `esm`. + Default is `iife`, a self-executing function, suitable for inclusion as a