Merge commit 'a0c28c943c2f4714fa340b22a583b96f5013090b'

This commit is contained in:
Bjørn Erik Pedersen 2019-04-20 15:19:38 +02:00
commit 0508ca1856
No known key found for this signature in database
GPG key ID: 330E6E2BD4859D8F
12 changed files with 164 additions and 103 deletions

View file

@ -100,7 +100,7 @@ Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as pr
## Mmark ## Mmark
Mmark is a [fork of BlackFriday][mmark] and markdown superset that is well suited for writing [IETF documentation][ietf]. You can see examples of the syntax in the [Mmark GitHub repository][mmarkgh] or the full syntax on [Miek Gieben's website][]. Mmark is a [fork of BlackFriday][mmark] and markdown superset that is well suited for writing [IETF documentation][ietf]. You can see examples of the syntax in the [Mmark GitHub repository][mmark] or the full syntax on [Miek Gieben's website][].
### Use Mmark ### Use Mmark
@ -253,8 +253,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
[mdguide]: https://www.markdownguide.org/ [mdguide]: https://www.markdownguide.org/
[mdtutorial]: http://www.markdowntutorial.com/ [mdtutorial]: http://www.markdowntutorial.com/
[Miek Gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/ [Miek Gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/
[mmark]: https://github.com/miekg/mmark [mmark]: https://github.com/mmarkdown/mmark
[mmarkgh]: https://github.com/miekg/mmark/wiki/Syntax
[org]: http://orgmode.org/ [org]: http://orgmode.org/
[pandoc]: http://www.pandoc.org/ [pandoc]: http://www.pandoc.org/
[Pygments]: http://pygments.org/ [Pygments]: http://pygments.org/

View file

@ -53,12 +53,15 @@ The examples above use two different delimiters, the difference being the `%` ch
### Shortcodes with Markdown ### Shortcodes with Markdown
The `%` character indicates that the shortcode's inner content---called in the [shortcode template][sctemps] with the [`.Inner` variable][scvars]---needs further processing by the page's rendering processor (i.e. markdown via Blackfriday). In the following example, Blackfriday would convert `**World**` to `<strong>World</strong>`: In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer (e.g. Blackfriday for Markdown), meaning they can be part of the generated table of contents, footnotes, etc.
If you want the old behavior, you can put the following line in the start of your shortcode template:
``` ```
{{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}} {{ $_hugo_config := `{ "version": 1 }` }}
``` ```
### Shortcodes Without Markdown ### Shortcodes Without Markdown
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML: The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML:

View file

@ -135,24 +135,16 @@ If you want to have just the default `tags` taxonomy, and remove the `categories
If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies). If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
### Preserve Taxonomy Values
By default, taxonomy names are normalized.
Therefore, if you want to have a taxonomy term with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, set the value for `preserveTaxonomyNames` to `true` in your [site config][config]. Hugo will then preserve special characters in taxonomy values but will still normalize them in URLs.
Note that if you use `preserveTaxonomyNames` and intend to manually construct URLs to the archive pages, you will need to pass the taxonomy values through the [`urlize` template function][].
{{% note %}} {{% note %}}
You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose. You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not. Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not.
{{% /note %}} {{% /note %}}
{{% warning "`preserveTaxonomyNames` behaviour change" %}} {{% warning %}}
Before 0.49, Hugo would make the first character upper case for the taxonomy values for titles even if `preserveTaxonomyNames` was active. This no longer the case, which (for instance) makes it possible to have fully lower-case values. The configuration option `preserveTaxonomyNames` was removed in Hugo 0.55.
If you actually need to title-ize these values, you can do so using the `strings.FirstUpper` template function. You can now use `.Page.Title` on the relevant taxonomy node to get the original value.
{{% /warning %}} {{% /warning %}}
## Add Taxonomies to Content ## Add Taxonomies to Content

View file

@ -84,7 +84,6 @@ The following is a list of values that can be used in a `permalink` definition i
Aliases can be used to create redirects to your page from other URLs. Aliases can be used to create redirects to your page from other URLs.
Aliases comes in two forms: Aliases comes in two forms:
1. Starting with a `/` meaning they are relative to the `BaseURL`, e.g. `/posts/my-blogpost/` 1. Starting with a `/` meaning they are relative to the `BaseURL`, e.g. `/posts/my-blogpost/`
@ -130,6 +129,8 @@ aliases:
--- ---
``` ```
From Hugo 0.55 you can also have page-relative aliases, so ` /es/posts/my-original-post/` can be simplified to the more portable `my-original-post/`
### How Hugo Aliases Work ### How Hugo Aliases Work
When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target. When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target.
@ -257,12 +258,29 @@ Or, if you are on Windows and do not have `grep` installed:
hugo config | FINDSTR /I canon hugo config | FINDSTR /I canon
``` ```
## Override URLs with Front Matter ## Set URL in Front Matter
In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content. In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content.
Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg]. Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg].
From Hugo 0.55, you can use URLs relative to the current site context (the language), which makes it simpler to maintain. For a Japanese translation, both of the following examples would get the same URL:
```markdown
---
title: "Custom URL!"
url: "/jp/custom/foo"
---
```
```markdown
---
title: "Custom URL!"
url: "custom/foo"
---
```
## Relative URLs ## Relative URLs
By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system. By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system.

View file

@ -211,9 +211,6 @@ permalinks
pluralizeListTitles (true) pluralizeListTitles (true)
: Pluralize titles in lists. : Pluralize titles in lists.
preserveTaxonomyNames (false)
: Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu").
publishDir ("public") publishDir ("public")
: The directory to where Hugo will write the final static site (the HTML files etc.). : The directory to where Hugo will write the final static site (the HTML files etc.).

View file

@ -43,7 +43,6 @@ Usage:
hugo [command] hugo [command]
Available Commands: Available Commands:
benchmark Benchmark Hugo by building a site a number of times.
check Contains some verification checks check Contains some verification checks
config Print the site configuration config Print the site configuration
convert Convert your content to different formats convert Convert your content to different formats
@ -57,43 +56,43 @@ Available Commands:
version Print the version number of Hugo version Print the version number of Hugo
Flags: Flags:
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/ -b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
-D, --buildDrafts include content marked as draft -D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content -E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future -F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/ --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--canonifyURLs (deprecated) if true, all relative URLs will be canonicalized using baseURL --cleanDestinationDir remove files from destination not found in static directories
--cleanDestinationDir remove files from destination not found in static directories --config string config file (default is path/config.yaml|json|toml)
--config string config file (default is path/config.yaml|json|toml) --configDir string config dir (default "config")
-c, --contentDir string filesystem path to content directory -c, --contentDir string filesystem path to content directory
--debug debug output --debug debug output
-d, --destination string filesystem path to write files to -d, --destination string filesystem path to write files to
--disableKinds stringSlice disable different kind of pages (home, RSS etc.) --disableKinds strings disable different kind of pages (home, RSS etc.)
--enableGitInfo add Git revision, date and author info to the pages --enableGitInfo add Git revision, date and author info to the pages
--forceSyncStatic copy all files when static is changed. -e, --environment string build environment
--gc enable to run some cleanup tasks (remove unused cache files) after the build --forceSyncStatic copy all files when static is changed.
-h, --help help for hugo --gc enable to run some cleanup tasks (remove unused cache files) after the build
--i18n-warnings print missing translations -h, --help help for hugo
--ignoreCache ignores the cache directory --i18n-warnings print missing translations
-l, --layoutDir string filesystem path to layout directory --ignoreCache ignores the cache directory
--log enable Logging -l, --layoutDir string filesystem path to layout directory
--logFile string log File path (if set, logging enabled automatically) --log enable Logging
--noChmod don't sync permission mode of files --logFile string log File path (if set, logging enabled automatically)
--noTimes don't sync modification time of files --minify minify any supported output format (HTML, XML etc.)
--pluralizeListTitles (deprecated) pluralize titles in lists using inflect (default true) --noChmod don't sync permission mode of files
--preserveTaxonomyNames (deprecated) preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu") --noTimes don't sync modification time of files
--quiet build in quiet mode --path-warnings print warnings on duplicate target paths etc.
--renderToMemory render to memory (only useful for benchmark testing) --quiet build in quiet mode
-s, --source string filesystem path to read files relative from --renderToMemory render to memory (only useful for benchmark testing)
--stepAnalysis display memory and timing of different steps of the program -s, --source string filesystem path to read files relative from
--templateMetrics display metrics about template executions --templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics --templateMetricsHints calculate some improvement hints when combined with --templateMetrics
-t, --theme string theme to use (located in /themes/THEMENAME/) -t, --theme strings themes to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory --themesDir string filesystem path to themes directory
--uglyURLs (deprecated) if true, use /filename.html instead of /filename/ --trace file write trace to file (not useful in general)
-v, --verbose verbose output -v, --verbose verbose output
--verboseLog verbose logging --verboseLog verbose logging
-w, --watch watch filesystem for changes and recreate as needed -w, --watch watch filesystem for changes and recreate as needed
Use "hugo [command] --help" for more information about a command. Use "hugo [command] --help" for more information about a command.
``` ```

View file

@ -1,8 +1,8 @@
--- ---
date: 2019-04-12 date: 2019-04-12
title: "0.55.1" title: "0.55.1: 3 Bug Fixes"
description: "0.55.1" description: "Fixes 3 issues introduced in 0.55.0."
categories: ["Releases"] categories: ["Releases"]
images: images:
- images/blog/hugo-bug-poster.png - images/blog/hugo-bug-poster.png

View file

@ -1,8 +1,8 @@
--- ---
date: 2019-04-17 date: 2019-04-17
title: "0.55.2" title: "Hugo 0.55.2: Some Important Bug Fixes"
description: "0.55.2" description: "Fixes some more issues introduced in Hugo 0.55.0."
categories: ["Releases"] categories: ["Releases"]
images: images:
- images/blog/hugo-bug-poster.png - images/blog/hugo-bug-poster.png

View file

@ -68,7 +68,7 @@ Given a media type and some additional configuration, you get an **Output Format
This is the full set of Hugo's built-in output formats: This is the full set of Hugo's built-in output formats:
{{< datatable "output" "formats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly">}} {{< datatable "output" "formats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly" "permalinkable" >}}
* A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined **as long as they resolve to a unique path on the file system**. In the above table, the best example of this is `AMP` vs. `HTML`. `AMP` has the value `amp` for `Path` so it doesn't overwrite the `HTML` version; e.g. we can now have both `/index.html` and `/amp/index.html`. * A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined **as long as they resolve to a unique path on the file system**. In the above table, the best example of this is `AMP` vs. `HTML`. `AMP` has the value `amp` for `Path` so it doesn't overwrite the `HTML` version; e.g. we can now have both `/index.html` and `/amp/index.html`.
* The `MediaType` must match the `Type` of an already defined media type. * The `MediaType` must match the `Type` of an already defined media type.
@ -120,6 +120,9 @@ The following is the full list of configuration options for output formats and t
`notAlternative` `notAlternative`
: enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term *alternative* and not *alternate* here, as it does not necessarily replace the other format. **Default:** `false`. : enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term *alternative* and not *alternate* here, as it does not necessarily replace the other format. **Default:** `false`.
`permalinkable`
: make `.Permalink` and `.RelPermalink` return the rendering Output Format rather than main ([see below](#link-to-output-formats)). This is enabled by default for `HTML` and `AMP`. **Default:** `false`.
## Output Formats for Pages ## Output Formats for Pages
A `Page` in Hugo can be rendered to multiple *output formats* on the file A `Page` in Hugo can be rendered to multiple *output formats* on the file
@ -173,7 +176,7 @@ outputs:
--- ---
``` ```
## Link to Output Formats ## List Output formats
Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`: Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`:
@ -183,13 +186,26 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an
{{ end -}} {{ end -}}
``` ```
Note that `.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). ## Link to Output Formats
This is how you link to a given output format: `.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template file they are being called from.
__from `single.json.json`:__
```go-html-template
{{ .RelPermalink }} > /that-page/
{{ with .OutputFormats.Get "json" -}}
{{ .RelPermalink }} > /that-page/index.json
{{- end }}
```
In order for them to return the output format of the current template file instead, the given output format should have its `permalinkable` setting set to true.
__Same template file as above with json output format's `permalinkable` set to true:__
```go-html-template ```go-html-template
{{ with .OutputFormats.Get "json" -}} {{ .RelPermalink }} > /that-page/index.json
<a href="{{ .Permalink }}">{{ .Name }}</a> {{ with .OutputFormats.Get "html" -}}
{{ .RelPermalink }} > /that-page/
{{- end }} {{- end }}
``` ```

View file

@ -77,7 +77,47 @@ The second argument in a partial call is the variable being passed down. The abo
This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`. This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`.
### Cached Partials ## Returning a value from a Partial
In addition to outputting markup, partials can be used to return a value of any type. In order to return a value, a partial must include a lone `return` statement.
### Example GetFeatured
```go-html-template
{{/* layouts/partials/GetFeatured.html */}}
{{ return first . (where site.RegularPages ".Params.featured" true) }}
```
```go-html-template
{{/* layouts/index.html */}}
{{ range partial "GetFeatured.html" 5 }}
[...]
{{ end }}
```
### Example GetImage
```go-html-template
{{/* layouts/partials/GetImage.html */}}
{{ $image := false }}
{{ with .Params.gallery }}
{{ $image = index . 0 }}
{{ end }}
{{ with .Params.image }}
{{ $image = . }}
{{ end }}
{{ return $image }}
```
```go-html-template
{{/* layouts/_default/single.html */}}
{{ with partial "GetImage.html" . }}
[...]
{{ end }}
```
{{% note %}}
Only one `return` statement is allowed per partial file.
{{% /note %}}
## Cached Partials
The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows: The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows:

View file

@ -124,6 +124,18 @@ Taxonomies can be ordered by either alphabetical key or by the number of content
### Order Alphabetically Example ### Order Alphabetically Example
In Hugo 0.55 and later you can do:
```go-html-template
<ul>
{{ range .Data.Terms.Alphabetical }}
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
{{ end }}
</ul>
```
Before that you would have to do something like:
```go-html-template ```go-html-template
<ul> <ul>
{{ $type := .Type }} {{ $type := .Type }}
@ -137,35 +149,6 @@ Taxonomies can be ordered by either alphabetical key or by the number of content
</ul> </ul>
``` ```
### Order by Popularity Example
```go-html-template
<ul>
{{ $type := .Type }}
{{ range $key, $value := .Data.Terms.ByCount }}
{{ $name := .Name }}
{{ $count := .Count }}
{{ with $.Site.GetPage (printf "/%s/%s" $type $name) }}
<li><a href="{{ .Permalink }}">{{ $name }}</a> {{ $count }}</li>
{{ end }}
{{ end }}
</ul>
```
### Order by Least Popular Example
```go-html-template
<ul>
{{ $type := .Type }}
{{ range $key, $value := .Data.Terms.ByCount.Reverse }}
{{ $name := .Name }}
{{ $count := .Count }}
{{ with $.Site.GetPage (printf "/%s/%s" $type $name) }}
<li><a href="{{ .Permalink }}">{{ $name }}</a> {{ $count }}</li>
{{ end }}
{{ end }}
</ul>
```
<!-- [See Also Taxonomy Lists](/templates/list/) --> <!-- [See Also Taxonomy Lists](/templates/list/) -->
@ -311,6 +294,20 @@ The following example displays all terms in a site's tags taxonomy:
### Example: List All Site Tags {#example-list-all-site-tags} ### Example: List All Site Tags {#example-list-all-site-tags}
In Hugo 0.55 and later you can simply do:
```go-html-template
<ul>
{{ range .Site.Taxonomies.tags }}
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
{{ end }}
</ul>
```
Before that you would do something like this:
{{< todo >}}Clean up rest of the taxonomy examples re Hugo 0.55.{{< /todo >}}
```go-html-template ```go-html-template
<ul id="all-tags"> <ul id="all-tags">
{{ range $name, $taxonomy := .Site.Taxonomies.tags }} {{ range $name, $taxonomy := .Site.Taxonomies.tags }}

View file

@ -3,7 +3,7 @@ publish = "public"
command = "hugo --gc --minify" command = "hugo --gc --minify"
[context.production.environment] [context.production.environment]
HUGO_VERSION = "0.55.0" HUGO_VERSION = "0.55.2"
HUGO_ENV = "production" HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true" HUGO_ENABLEGITINFO = "true"
@ -11,20 +11,20 @@ HUGO_ENABLEGITINFO = "true"
command = "hugo --gc --minify --enableGitInfo" command = "hugo --gc --minify --enableGitInfo"
[context.split1.environment] [context.split1.environment]
HUGO_VERSION = "0.55.0" HUGO_VERSION = "0.55.2"
HUGO_ENV = "production" HUGO_ENV = "production"
[context.deploy-preview] [context.deploy-preview]
command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL" command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"
[context.deploy-preview.environment] [context.deploy-preview.environment]
HUGO_VERSION = "0.55.0" HUGO_VERSION = "0.55.2"
[context.branch-deploy] [context.branch-deploy]
command = "hugo --gc --minify -b $DEPLOY_PRIME_URL" command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
[context.branch-deploy.environment] [context.branch-deploy.environment]
HUGO_VERSION = "0.55.0" HUGO_VERSION = "0.55.2"
[context.next.environment] [context.next.environment]
HUGO_ENABLEGITINFO = "true" HUGO_ENABLEGITINFO = "true"