diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2020-05-06 12:12:57 +0200 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2020-05-06 12:12:57 +0200 |
commit | e4621446ce8b9f677d00ed208154e7f106bc9980 (patch) | |
tree | 1e666fe8e257b322e51f184296cceee4f41042b5 /docs | |
parent | 01befcce35ec992d195ce1b9a6a1eeda693cb5a8 (diff) | |
parent | 89044b8f8795f17c36396c67823183a20fc88139 (diff) |
Merge commit '89044b8f8795f17c36396c67823183a20fc88139'
Diffstat (limited to 'docs')
46 files changed, 231 insertions, 40 deletions
diff --git a/docs/content/en/commands/hugo_gen_doc.md b/docs/content/en/commands/hugo_gen_doc.md index 2c003a972..657550886 100644 --- a/docs/content/en/commands/hugo_gen_doc.md +++ b/docs/content/en/commands/hugo_gen_doc.md @@ -13,7 +13,7 @@ Generate Markdown documentation for the Hugo CLI. Generate Markdown documentation for the Hugo CLI. This command is, mostly, used to create up-to-date documentation -of Hugo's command-line interface for http://gohugo.io/. +of Hugo's command-line interface for https://gohugo.io/. It creates one Markdown file per command with front matter suitable for rendering in Hugo. diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md index ea0568616..da530343a 100644 --- a/docs/content/en/content-management/formats.md +++ b/docs/content/en/content-management/formats.md @@ -34,7 +34,7 @@ The current list of content formats in Hugo: |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.| -|RST|rst|Needs [RST](http://docutils.sourceforge.net/rst.html) installed.| +|RST|rst|Needs [RST](https://docutils.sourceforge.io/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.| @@ -88,7 +88,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are [mmark]: https://github.com/mmarkdown/mmark [org]: https://orgmode.org/ [pandoc]: https://www.pandoc.org/ -[Pygments]: http://pygments.org/ -[rest]: http://docutils.sourceforge.net/rst.html +[Pygments]: https://pygments.org/ +[rest]: https://docutils.sourceforge.io/rst.html [sc]: /content-management/shortcodes/ [sct]: /templates/shortcode-templates/ diff --git a/docs/content/en/content-management/shortcodes.md b/docs/content/en/content-management/shortcodes.md index 0244c4a88..599ce159c 100644 --- a/docs/content/en/content-management/shortcodes.md +++ b/docs/content/en/content-management/shortcodes.md @@ -423,7 +423,7 @@ To learn more about creating custom shortcodes, see the [shortcode template docu [Instagram]: https://www.instagram.com/ [pagevariables]: /variables/page/ [partials]: /templates/partials/ -[Pygments]: http://pygments.org/ +[Pygments]: https://pygments.org/ [quickstart]: /getting-started/quick-start/ [sctemps]: /templates/shortcode-templates/ [scvars]: /variables/shortcodes/ diff --git a/docs/content/en/contribute/development.md b/docs/content/en/contribute/development.md index bd76f9bbe..000f478fc 100644 --- a/docs/content/en/contribute/development.md +++ b/docs/content/en/contribute/development.md @@ -107,7 +107,7 @@ On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew]( brew install hub ``` -Now we'll create an [alias in Bash](http://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`: +Now we'll create an [alias in Bash](https://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`: ``` echo "alias git='hub'" >> ~/.bash_profile diff --git a/docs/content/en/contribute/documentation.md b/docs/content/en/contribute/documentation.md index c4bbbd8bb..014f6761e 100644 --- a/docs/content/en/contribute/documentation.md +++ b/docs/content/en/contribute/documentation.md @@ -229,7 +229,7 @@ Which will render as follows in the Hugo docs: > Without the threat of punishment, there is no joy in flight. - [Kobo Abe][abe] {{% note "Blockquotes `!=` Admonitions" %}} -Previous versions of Hugo documentation used blockquotes to draw attention to text. This is *not* the [intended semantic use of `<blockquote>`](http://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting. To note or warn your user of specific information, use the admonition shortcodes that follow. +Previous versions of Hugo documentation used blockquotes to draw attention to text. This is *not* the [intended semantic use of `<blockquote>`](https://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting. To note or warn your user of specific information, use the admonition shortcodes that follow. {{% /note %}} ## Admonitions @@ -330,5 +330,5 @@ Similar to [contributing to Hugo development](/contribute/development/), the Hug [ghforking]: https://help.github.com/articles/fork-a-repo/ [hugodev]: /contribute/development/ [shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown -[sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions +[sourceforge]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions [templating function]: /functions/ diff --git a/docs/content/en/functions/jsonify.md b/docs/content/en/functions/jsonify.md index 5c670244f..a6028fcda 100644 --- a/docs/content/en/functions/jsonify.md +++ b/docs/content/en/functions/jsonify.md @@ -5,13 +5,13 @@ description: Encodes a given object to JSON. godocref: date: 2017-02-01 publishdate: 2017-02-01 -lastmod: 2017-02-01 +lastmod: 2020-04-13 categories: [functions] menu: docs: parent: "functions" keywords: [strings,json] -signature: ["jsonify INPUT"] +signature: ["jsonify INPUT", "jsonify OPTIONS INPUT"] workson: [] hugoversion: relatedfuncs: [plainify] @@ -19,8 +19,18 @@ deprecated: false aliases: [] --- +Jsonify encodes a given object to JSON. + +To customize the printing of the JSON, pass a dictionary of options as the first +argument. Supported options are "prefix" and "indent". Each JSON element in +the output will begin on a new line beginning with *prefix* followed by one or +more copies of *indent* according to the indentation nesting. + + ``` {{ dict "title" .Title "content" .Plain | jsonify }} +{{ dict "title" .Title "content" .Plain | jsonify (dict "indent" " ") }} +{{ dict "title" .Title "content" .Plain | jsonify (dict "prefix" " " "indent" " ") }} ``` See also the `.PlainWords`, `.Plain`, and `.RawContent` [page variables][pagevars]. diff --git a/docs/content/en/functions/range.md b/docs/content/en/functions/range.md index f80967c41..26f636d4d 100644 --- a/docs/content/en/functions/range.md +++ b/docs/content/en/functions/range.md @@ -20,6 +20,6 @@ draft: false aliases: [] --- -Just like in the Go programming language, Go and Hugo templates make heavy use of `range` to iterate over a map, array or slice. +Just like in the Go programming language, Go and Hugo templates make heavy use of `range` to iterate over a map, array or slice. Other templating languages use a foreach for the equivalent functionality. `range` is fundamental to templating in Hugo. (See the [Introduction to Hugo Templates](/templates/introduction/) for more examples.) diff --git a/docs/content/en/functions/safeURL.md b/docs/content/en/functions/safeURL.md index 2e0733142..c132ddf05 100644 --- a/docs/content/en/functions/safeURL.md +++ b/docs/content/en/functions/safeURL.md @@ -69,4 +69,4 @@ With the `.URL` page variable piped through `safeURL`, we get the desired output [configuration]: /getting-started/configuration/ [menus]: /content-management/menus/ -[RFC 3986]: http://tools.ietf.org/html/rfc3986 +[RFC 3986]: https://tools.ietf.org/html/rfc3986 diff --git a/docs/content/en/getting-started/configuration.md b/docs/content/en/getting-started/configuration.md index 038793454..abce0286d 100644 --- a/docs/content/en/getting-started/configuration.md +++ b/docs/content/en/getting-started/configuration.md @@ -298,17 +298,21 @@ enableemoji: true {{< new-in "0.66.0" >}} -The `build` configuration section contains global build-realated configuration options. +The `build` configuration section contains global build-related configuration options. {{< code-toggle file="config">}} [build] useResourceCacheWhen="fallback" +writeStats = false {{< /code-toggle >}} useResourceCacheWhen : When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available. +writeStats {{< new-in "0.69.0" >}} +: When enabled, a file named `hugo_stats.json` will be written to your project root with some aggregated data about the build, e.g. list of HTML entities published to be used to do [CSS pruning](/hugo-pipes/postprocess/#css-purging-with-postcss). If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). It's also worth mentioning that, due to the nature of the partial server builds, new HTML entities will be added when you add or change them while the server is running, but the old values will not be removed until you restart the server or run a regular `hugo` build. + ## Configure Server {{< new-in "0.67.0" >}} diff --git a/docs/content/en/getting-started/installing.md b/docs/content/en/getting-started/installing.md index 23f25f477..4583cff94 100644 --- a/docs/content/en/getting-started/installing.md +++ b/docs/content/en/getting-started/installing.md @@ -86,6 +86,12 @@ If you are on a Windows machine and use [Scoop][] for package management, you ca scoop install hugo ``` +Or install the extended version with: + +```bash +scoop install hugo-extended +``` + ### Source #### Prerequisite Tools @@ -517,7 +523,7 @@ Now that you've installed Hugo, read the [Quick Start guide][quickstart] and exp [installgo]: https://golang.org/dl/ [linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux [Path Editor]: https://patheditor2.codeplex.com/ -[pygments]: http://pygments.org +[pygments]: https://pygments.org [quickstart]: /getting-started/quick-start/ [redhatforum]: https://discourse.gohugo.io/t/solved-fedora-copr-repository-out-of-service/2491 [releases]: https://github.com/gohugoio/hugo/releases diff --git a/docs/content/en/hosting-and-deployment/hosting-on-github.md b/docs/content/en/hosting-and-deployment/hosting-on-github.md index 9307a2758..9630c57ff 100644 --- a/docs/content/en/hosting-and-deployment/hosting-on-github.md +++ b/docs/content/en/hosting-and-deployment/hosting-on-github.md @@ -42,7 +42,7 @@ To create a Project Pages site, choose a method from the *Project Pages* section ## GitHub User or Organization Pages -As mentioned [the GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations: +As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations: 1. You must use a `<USERNAME>.github.io` to host your **generated** content 2. Content from the `master` branch will be used to publish your GitHub Pages site @@ -54,7 +54,7 @@ This is a much simpler setup as your Hugo files and generated content are publis 1. Create a `<YOUR-PROJECT>` (e.g. `blog`) repository on GitHub. This repository will contain Hugo's content and other source files. 2. Create a `<USERNAME>.github.io` GitHub repository. This is the repository that will contain the fully rendered version of your Hugo website. 3. `git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>` -4. Paste your existing Hugo project into a new local `<YOUR-PROJECT>` repository. Make sure your website works locally (`hugo server` or `hugo server -t <YOURTHEME>`) and open your browser to <http://localhost:1313>. +4. Paste your existing Hugo project into the new local `<YOUR-PROJECT>` repository. Make sure your website works locally (`hugo server` or `hugo server -t <YOURTHEME>`) and open your browser to <http://localhost:1313>. 5. Once you are happy with the results: * Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server * Before proceeding run `rm -rf public` to completely remove the `public` directory diff --git a/docs/content/en/hosting-and-deployment/hugo-deploy.md b/docs/content/en/hosting-and-deployment/hugo-deploy.md index 1156b2fee..d42ffe6c7 100644 --- a/docs/content/en/hosting-and-deployment/hugo-deploy.md +++ b/docs/content/en/hosting-and-deployment/hugo-deploy.md @@ -19,7 +19,7 @@ aliases: [] toc: true --- -You can use the "hugo deploy" command to upload your site directly to a Google Cloud Storage (GCS) bucket, an AWS S3 bucket, and/or an Azure Storage bucket. +You can use the "hugo deploy" command to upload your site directly to a Google Cloud Storage (GCS) bucket, an AWS S3 bucket, and/or an Azure Storage container. ## Assumptions @@ -46,7 +46,7 @@ Follow the [AWS instructions for how to create a bucket](https://docs.aws.amazon ### Azure Storage -Follow the [Azure instructions for how to create a bucket](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal). +Follow the [Azure instructions for how to create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal). ## Configure the deployment diff --git a/docs/content/en/hugo-pipes/postprocess.md b/docs/content/en/hugo-pipes/postprocess.md new file mode 100755 index 000000000..962d0ffdf --- /dev/null +++ b/docs/content/en/hugo-pipes/postprocess.md @@ -0,0 +1,70 @@ +--- +title: PostProcess +description: Allows delaying of resource transformations to after the build. +date: 2020-04-09 +categories: [asset management] +keywords: [] +menu: + docs: + parent: "pipes" + weight: 39 +weight: 39 +sections_weight: 39 +--- + +Marking a resource with `resources.PostProcess` delays any transformations to after the build, typically because one or more of the steps in the transformation chain depends on the result of the build (e.g. files in `public`).{{< new-in "0.69.0" >}} + +A prime use case for this is [CSS purging with PostCSS](#css-purging-with-postcss). + +There are currently two limitations to this: + +1. This only works in `*.html` templates (i.e. templates that produces HTML files). +2. You cannot manipulate the values returned from the resource's methods. E.g. the `upper` in this example will not work as expected: + + ```go-html-template + {{ $css := resources.Get "css/main.css" }} + {{ $css = $css | resources.PostCSS | minify | fingerprint | resources.PostProcess }} + {{ $css.RelPermalink | upper }} + ``` + +## CSS purging with PostCSS + +{{% note %}} +There are several ways to set up CSS purging with PostCSS in Hugo. If you have a simple project, you should consider going the simpler route and drop the use of `resources.PostProcess` and just extract keywords from the templates. See the [Tailwind documentation](https://tailwindcss.com/docs/controlling-file-size/#app) for some examples. +{{% /note %}} + +The below configuration will write a `hugo_stats.json` file to the project root as part of the build. If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). + +```toml +[build] + writeStats = true +``` + +```js +const purgecss = require('@fullhuman/postcss-purgecss')({ + content: [ './hugo_stats.json' ], + defaultExtractor: (content) => { + let els = JSON.parse(content).htmlElements; + return els.tags.concat(els.classes, els.ids); + } +}); + +module.exports = { + plugins: [ + require('tailwindcss'), + require('autoprefixer'), + ...(process.env.HUGO_ENVIRONMENT === 'production' ? [ purgecss ] : []) + ] +}; +``` + +Note that in the example above, the "CSS purge step" will only be applied to the production build. This means that you need to do something like this in your head template to build and include your CSS: + +```go-html-template +{{ $css := resources.Get "css/main.css" }} +{{ $css = $css | resources.PostCSS }} +{{ if hugo.IsProduction }} +{{ $css = $css | minify | fingerprint | resources.PostProcess }} +{{ end }} +<link href="{{ $css.RelPermalink }}" rel="stylesheet" /> +``` diff --git a/docs/content/en/news/0.69.0-relnotes/hugo-69-easter-featured.png b/docs/content/en/news/0.69.0-relnotes/hugo-69-easter-featured.png Binary files differnew file mode 100644 index 000000000..d1b413142 --- /dev/null +++ b/docs/content/en/news/0.69.0-relnotes/hugo-69-easter-featured.png diff --git a/docs/content/en/news/0.69.0-relnotes/index.md b/docs/content/en/news/0.69.0-relnotes/index.md index 2a96cd9ef..13bb1b76b 100644 --- a/docs/content/en/news/0.69.0-relnotes/index.md +++ b/docs/content/en/news/0.69.0-relnotes/index.md @@ -1,12 +1,12 @@ --- date: 2020-04-10 -title: "0.69.0" -description: "0.69.0" +title: "Post Build Resource Transformations" +description: "Hugo 0.69.0 allows you to delay resource processing to after the build, the prime use case being removal of unused CSS." categories: ["Releases"] --- - It's Eeaster, a time for mysteries and puzzles. And at first glance, this Hugo release looks a little mysterious. The core of if is a mind-twister: +**It's Eeaster, a time for mysteries and puzzles.** And at first glance, this Hugo release looks a little mysterious. The core of if is a mind-twister: ```go-html-template {{ $css := resources.Get "css/main.css" }} diff --git a/docs/content/en/showcase/arolla-cocoon/bio.md b/docs/content/en/showcase/arolla-cocoon/bio.md index f01228828..dcccc8b50 100644 --- a/docs/content/en/showcase/arolla-cocoon/bio.md +++ b/docs/content/en/showcase/arolla-cocoon/bio.md @@ -1,5 +1,5 @@ -[Camping Arolla](http://www.camping-arolla.com/) is located in the heart of the Swiss Alps, at an altitude of 1.950 meters. +[Camping Arolla](https://www.camping-arolla.com) is located in the heart of the Swiss Alps, at an altitude of 1.950 meters. The site is built by: diff --git a/docs/content/en/showcase/arolla-cocoon/index.md b/docs/content/en/showcase/arolla-cocoon/index.md index 3fe304056..63f139adf 100644 --- a/docs/content/en/showcase/arolla-cocoon/index.md +++ b/docs/content/en/showcase/arolla-cocoon/index.md @@ -8,7 +8,7 @@ byline: "[Didier Divinerites](https://github.com/divinerites)" --- -Swiss [Arolla campsite](http://www.camping-arolla.com/) runs the highest campsite in Europe and I'm completely re-doing their actuel Website with Hugo. +Swiss [Arolla campsite](https://www.camping-arolla.com) runs the highest campsite in Europe and I'm completely re-doing their actuel |