Squashed 'docs/' changes from 0f2bf19..13097da

13097da Update shortcode docs vs 0.55 9a7e192 Update URL docs for relative URLs etc bd58dd8 Adjust Output Formats docs f3e9fbc Document output format `permalinkable` 3778ce6 Update partials.md 7b207a4 Partial: Update variable name in example 7d7b1f0 Document partials returning a value. 7ae93b7 Merge branch 'temp552' 81910d2 releaser: Add release notes to /docs for release of 0.55.2 c166cef Fix typo 23adeb6 Point mmark links to its new repository 369a873 Merge branch 'temp551' eb6097e Bump to 0.55.1 766ee61 releaser: Add release notes to /docs for release of 0.55.1 a5a5f5d Start of taxonomy docs update for Hugo 0.55 fb5f75e Remove the space in `. RelPermalink` git-subtree-dir: docs git-subtree-split: 13097da
gohugoio · Apr 20, 2019 · a0c28c943c2f4714fa340b22a583b96f5013090b · a0c28c9
1 parent 8b73644
commit a0c28c943c2f4714fa340b22a583b96f5013090b
diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md
@@ -100,7 +100,7 @@ Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as pr
 
 ## 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
 
@@ -253,8 +253,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
 [mdguide]: https://www.markdownguide.org/
 [mdtutorial]: http://www.markdowntutorial.com/
 [Miek Gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/
-[mmark]: https://github.com/miekg/mmark
-[mmarkgh]: https://github.com/miekg/mmark/wiki/Syntax
+[mmark]: https://github.com/mmarkdown/mmark
 [org]: http://orgmode.org/
 [pandoc]: http://www.pandoc.org/
 [Pygments]: http://pygments.org/

diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md
@@ -53,12 +53,15 @@ The examples above use two different delimiters, the difference being the `%` ch
 
 ### 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
 
 The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML:

diff --git a/content/en/content-management/taxonomies.md b/content/en/content-management/taxonomies.md
@@ -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).
 
-### 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 %}}
 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.
 {{% /note %}}
 
-{{% warning "`preserveTaxonomyNames` behaviour change" %}}
-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.
+{{% warning %}}
+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 %}}
 
 ## Add Taxonomies to Content

diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md
@@ -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 comes in two forms:
 
 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
 
 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
 ```
 
-## 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.
 
 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
 
 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.

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

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

diff --git a/content/en/news/0.55.1-relnotes/index.md b/content/en/news/0.55.1-relnotes/index.md
@@ -0,0 +1,53 @@
+
+---
+date: 2019-04-12
+title: "0.55.1: 3 Bug Fixes"
+description: "Fixes 3 issues introduced in 0.55.0."
+categories: ["Releases"]
+images:
+- images/blog/hugo-bug-poster.png
+
+---
+
+
+
+This is a bug-fix release with a couple of important fixes.
+
+
+Hugo now has:
+
+* 34225+ [stars](https://github.com/gohugoio/hugo/stargazers)
+* 439+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
+* 307+ [themes](http://themes.gohugo.io/)
+
+
+## Notes
+
+* Replace deprecated .GetParam usage [27a8049d](https://github.com/gohugoio/hugo/commit/27a8049da7996b703d02083182b84a002eae2599) [@bep](https://github.com/bep) [#5834](https://github.com/gohugoio/hugo/issues/5834)
+
+## Enhancements
+
+### Core
+
+* Add a test for parent's resources in shortcode [8d7607ae](https://github.com/gohugoio/hugo/commit/8d7607aed10b3fe7373126ff5fa7dae36c559d7f) [@bep](https://github.com/bep) [#5833](https://github.com/gohugoio/hugo/issues/5833)
+
+### Other
+
+* Remove the space in `. RelPermalink` [7966c0b5](https://github.com/gohugoio/hugo/commit/7966c0b5b7b2297527f8be9040b793de5e4e3f48) [@yihui](https://github.com/yihui) 
+
+## Fixes
+
+### Core
+
+* Fix simple menu config [9e9a1f92](https://github.com/gohugoio/hugo/commit/9e9a1f92baf151f8d840d6b5b963945d1410ce25) [@bep](https://github.com/bep) 
+
+### Other
+
+* Fix [4d425a86](https://github.com/gohugoio/hugo/commit/4d425a86f5c03a5cca27d4e0f99d61acbb938d80) [@bep](https://github.com/bep) 
+* Fix paginator refresh on server change [f7375c49](https://github.com/gohugoio/hugo/commit/f7375c497239115cd30ae42af6b4d298e4e7ad7d) [@bep](https://github.com/bep) [#5838](https://github.com/gohugoio/hugo/issues/5838)
+* Fix .RSSLinke deprecation message [3b86b4a9](https://github.com/gohugoio/hugo/commit/3b86b4a9f5ce010c9714d813d5b8ecddda22c69f) [@bep](https://github.com/bep) [#4427](https://github.com/gohugoio/hugo/issues/4427)
+
+
+
+
+
diff --git a/content/en/news/0.55.2-relnotes/index.md b/content/en/news/0.55.2-relnotes/index.md
@@ -0,0 +1,51 @@
+
+---
+date: 2019-04-17
+title: "Hugo 0.55.2: Some Important Bug Fixes"
+description: "Fixes some more issues introduced in Hugo 0.55.0."
+categories: ["Releases"]
+images:
+- images/blog/hugo-bug-poster.png
+
+---
+
+
+
+This is a bug-fix release with a couple of important fixes.
+
+
+Hugo now has:
+
+* 34386+ [stars](https://github.com/gohugoio/hugo/stargazers)
+* 439+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
+* 307+ [themes](http://themes.gohugo.io/)
+
+## Enhancements
+
+### Templates
+
+* Handle late transformation of templates [2957795f](https://github.com/gohugoio/hugo/commit/2957795f5276cc9bc8d438da2d7d9b61defea225) [@bep](https://github.com/bep) [#5865](https://github.com/gohugoio/hugo/issues/5865)
+
+### Core
+
+* Add more tests for Permalinkable [35f41834](https://github.com/gohugoio/hugo/commit/35f41834ea3a8799b9b7eda360cf8d30b1b727ba) [@bep](https://github.com/bep) [#5849](https://github.com/gohugoio/hugo/issues/5849)
+
+## Fixes
+
+### Core
+
+* Fix Pages reinitialization on rebuilds [9b17cbb6](https://github.com/gohugoio/hugo/commit/9b17cbb62a056ea7e26b1146cbf3ba42f5acf805) [@bep](https://github.com/bep) [#5833](https://github.com/gohugoio/hugo/issues/5833)
+* Fix shortcode namespace issue [56550d1e](https://github.com/gohugoio/hugo/commit/56550d1e449f45ebee398ac8a9e3b9818b3ee60e) [@bep](https://github.com/bep) [#5863](https://github.com/gohugoio/hugo/issues/5863)
+* Fix false WARNINGs in lang prefix check [7881b096](https://github.com/gohugoio/hugo/commit/7881b0965f8b83d03379e9ed102cd0c3bce297e2) [@bep](https://github.com/bep) [#5860](https://github.com/gohugoio/hugo/issues/5860)
+* Fix bundle resource publishing when multiple output formats [49d0a826](https://github.com/gohugoio/hugo/commit/49d0a82641581aa7dd66b9d5e8c7d75e23260083) [@bep](https://github.com/bep) [#5858](https://github.com/gohugoio/hugo/issues/5858)
+* Fix panic for unused taxonomy content files [b799b12f](https://github.com/gohugoio/hugo/commit/b799b12f4a693dfeae8a5a362f131081a727bb8f) [@bep](https://github.com/bep) [#5847](https://github.com/gohugoio/hugo/issues/5847)
+* Fix dates for sections with dates in front matter [70148672](https://github.com/gohugoio/hugo/commit/701486728e21bc0c6c78c2a8edb988abdf6116c7) [@bep](https://github.com/bep) [#5854](https://github.com/gohugoio/hugo/issues/5854)
+
+### Other
+
+* Fix WeightedPages in union etc. [f2795d4d](https://github.com/gohugoio/hugo/commit/f2795d4d2cef30170af43327f3ff7114923833b1) [@bep](https://github.com/bep) [#5850](https://github.com/gohugoio/hugo/issues/5850)
+
+
+
+
+
diff --git a/content/en/templates/output-formats.md b/content/en/templates/output-formats.md
@@ -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:
 
-{{< 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`.
 * 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`
 : 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
 
 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>`:
 
@@ -183,13 +186,26 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an
 {{ 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" -}}
-<a href="{{ .Permalink }}">{{ .Name }}</a>
+{{ .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
+{{ .RelPermalink }} > /that-page/index.json
+{{ with  .OutputFormats.Get "html" -}}
+{{ .RelPermalink }} > /that-page/
 {{- end }}
 ```