Merge commit '90ad8045056167004d27857a95542936657b8a16'

35 files changed, 306 insertions, 128 deletions

diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md
index ad3a1b55d..5c604fdeb 100644
--- a/docs/content/en/content-management/comments.md
+++ b/docs/content/en/content-management/comments.md
@@ -4,7 +4,6 @@ linktitle: Comments
 description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
 date: 2017-02-01
 publishdate: 2017-02-01
-lastmod: 2017-03-09
 keywords: [sections,content,organization]
 categories: [project organization, fundamentals]
 menu:
@@ -60,7 +59,7 @@ These are some alternatives to Disqus:
 * [Muut](https://muut.com/)
 * [Remark42](https://remark42.com/) (Open source, Golang, Easy to run docker)
 * [Staticman](https://staticman.net/)
-* [Talkyard](https://www.talkyard.io/blog-comments) (Open source, & serverless hosting)
+* [Talkyard](https://blog-comments.talkyard.io/) (Open source, & serverless hosting)
 * [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues)
 
 [configuration]: /getting-started/configuration/
diff --git a/docs/content/en/content-management/image-processing/index.md b/docs/content/en/content-management/image-processing/index.md
index 710c260ca..f2748f5db 100644
--- a/docs/content/en/content-management/image-processing/index.md
+++ b/docs/content/en/content-management/image-processing/index.md
@@ -28,7 +28,11 @@ content/
         └── sunset.jpg    <-- page resource
 ```
 
-To access an image as a page resource:
+## The Image Resource
+
+The `image` resource gives you access to image-specific attributes like the picture's `Width` and `Height`, as well as powerful processing methods and filters. More on that below.
+
+Note that the `image` resource can also be retrieved from a [global resource]({{< relref "/hugo-pipes/introduction#from-file-to-resource" >}})
 
 ```go-html-template
 {{ $image := .Resources.GetMatch "sunset.jpg" }}
diff --git a/docs/content/en/content-management/multilingual.md b/docs/content/en/content-management/multilingual.md
index d1e7965b2..e2450bb29 100644
--- a/docs/content/en/content-management/multilingual.md
+++ b/docs/content/en/content-management/multilingual.md
@@ -4,7 +4,6 @@ linktitle: Multilingual
 description: Hugo supports the creation of websites with multiple languages side by side.
 date: 2017-01-10
 publishdate: 2017-01-10
-lastmod: 2017-01-10
 categories: [content management]
 keywords: [multilingual,i18n, internationalization]
 menu:
@@ -335,13 +334,13 @@ This article has 101 words.
 
 ### Query a singular/plural translation
 
-In order to meet singular/plural requirement, you must pass a dictionary (map) with a numeric `.Count` property to the `i18n` function. The below example uses `.ReadingTime` variable which has a built-in `.Count` property.
+In other to meet singular/plural requirement, you must pass a dictionary (map) with a numeric `.Count` property to the `i18n` function. The below example uses `.ReadingTime` variable which has a built-in `.Count` property.
 
 ```go-html-template
 {{ i18n "readingTime" .ReadingTime }}
 ```
 
-The function will read `.Count` from `.ReadingTime` and evaluate where the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id:
+The function will read `.Count` from `.ReadingTime` and evaluate whether the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file:
 
 {{< code-toggle file="i18n/en-US" >}}
 [readingTime]
@@ -349,7 +348,7 @@ one = "One minute to read"
 other = "{{.Count}} minutes to read"
 {{< /code-toggle >}}
 
-Assume `.ReadingTime.Count` in the context has value of 525600. The result will be:
+Assuming `.ReadingTime.Count` in the context has value is 525600. The result will be:
 
 ```text
 525600 minutes to read
@@ -361,7 +360,7 @@ If `.ReadingTime.Count` in the context has value is 1. The result is:
 One minute to read
 ```
 
-In case you need to pass custom data: (`(dict "Count" 25)` is minimum requirement)
+In case you need to pass a custom data: (`(dict "Count" numeric_value_only)` is minimum requirement)
 
 ```go-html-template
 {{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }}
@@ -507,6 +506,40 @@ The rendering of the main navigation works as usual. `.Site.Menus` will just con
 </ul>
 ```
 
+### Dynamically localizing menus with i18n
+While customizing menus per language is useful, your config file can become hard to maintain if you have a lot of languages
+
+If your menus are the same in all languages (ie. if the only thing that changes is the translated name) you can use the `.Identifier` as a translation key for the menu name:
+
+{{< code-toggle file="config" >}}
+[[menu.main]]
+name = "About me"
+url = "about"
+weight = 1
+identifier = "about"
+{{< /code-toggle >}}
+
+You now need to specify the translations for the menu keys in the i18n files:
+
+{{< code file="i18n/pt.toml" >}}
+[about]
+other="Sobre mim"
+{{< /code >}}
+
+And do the appropriate changes in the menu code to use the `i18n` tag with the `.Identifier` as a key. You will also note that here we are using a `default` to fall back to `.Name`, in case the `.Identifier` key is also not present in the language specified in the `defaultContentLanguage` configuration.
+
+{{< code file="layouts/partials/menu.html" >}}
+<ul>
+    {{- $currentPage := . -}}
+    {{ range .Site.Menus.main -}}
+    <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
+        <a href="{{ .URL | absLangURL }}">{{ i18n .Identifier | default .Name}}</a>
+    </li>
+    {{- end }}
+</ul>
+{{< /code >}}
+                
+
 ## Missing Translations
 
 If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
@@ -535,6 +568,12 @@ To support Multilingual mode in your themes, some considerations must be taken f
 
 If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
 
+
+## Generate multilingual content with `hugo new`
+Currently, `hugo new` is not ready to support generating multilingual content. But there is a [proposal topic](https://github.com/gohugoio/hugo/issues/7732) about this in Github issue to discuss how it should work.
+
+
+
 [abslangurl]: /functions/abslangurl
 [config]: /getting-started/configuration/
 [contenttemplate]: /templates/single-page-templates/
diff --git a/docs/content/en/content-management/page-bundles.md b/docs/content/en/content-management/page-bundles.md
index 9561ea2e9..924efccd2 100644
--- a/docs/content/en/content-management/page-bundles.md
+++ b/docs/content/en/content-management/page-bundles.md
@@ -64,26 +64,27 @@ content/
 In the above example `content/` directory, there are four leaf
 bundles:
 
-about
+`about`
 : This leaf bundle is at the root level (directly under
     `content` directory) and has only the `index.md`.
 
-my-post
+`my-post`
 : This leaf bundle has the `index.md`, two other content
     Markdown files and two image files.
 
-image1
-: This image is a page resource of `my-post`
+- image1, image2: 
+These images are page resources of `my-post`
     and only available in `my-post/index.md` resources.
 
-image2
-: This image is a page resource of `my-post`
-    and only available in `my-post/index.md` resources.
+- content1, content2: 
+These content files are page resources of `my-post`
+    and only available in `my-post/index.md` resources. 
+    They will **not** be rendered as individual pages.
 
-my-other-post
+`my-other-post`
 : This leaf bundle has only the `index.md`.
 
-another-leaf-bundle
+`another-leaf-bundle`
 : This leaf bundle is nested under couple of
     directories. This bundle also has only the `index.md`.
 
diff --git a/docs/content/en/content-management/page-resources.md b/docs/content/en/content-management/page-resources.md
index 9f2c0cfab..24b1d03ed 100644
--- a/docs/content/en/content-management/page-resources.md
+++ b/docs/content/en/content-management/page-resources.md
@@ -131,7 +131,7 @@ name
 : Sets the value returned in `Name`.
 
 {{% warning %}}
-The methods `Match` and `GetMatch` use `Name` to match the resources.
+The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
 {{%/ warning %}}
 
 title
diff --git a/docs/content/en/content-management/syntax-highlighting.md b/docs/content/en/content-management/syntax-highlighting.md
index 8ff270c54..5195b8211 100644
--- a/docs/content/en/content-management/syntax-highlighting.md
+++ b/docs/content/en/content-management/syntax-highlighting.md
@@ -80,6 +80,20 @@ func GetTitleFunc(style string) func(s string) string {
 }
 {{< / highlight >}}
 
+## Highlight Hugo/GO Template Code
+
+For highlighting Hugo/GO template code on your page, add `/*` after the opening double curly braces and `*/` before closing curly braces.
+
+``` go
+{{</*/* myshortcode */*/>}}
+```
+
+Gives this:
+
+``` go
+{{</* myshortcode */>}}
+```
+
 ## Highlight Template Func
 
 See [Highlight](/functions/highlight/).
diff --git a/docs/content/en/functions/RenderString.md b/docs/content/en/functions/RenderString.md
index 1b77f6a38..e414b11ca 100644
--- a/docs/content/en/functions/RenderString.md
+++ b/docs/content/en/functions/RenderString.md
@@ -14,8 +14,6 @@ signature: [".RenderString MARKUP"]
 
 `.RenderString` is a method on `Page` that renders some markup to HTML using the content renderer defined for that page (if not set in the options).
 
-*Note* that this method does not parse and render shortcodes.
-
 The method takes an optional map argument with these options:
 
 display ("inline")
diff --git a/docs/content/en/functions/i18n.md b/docs/content/en/functions/i18n.md
index 7d88292b9..34a6ff022 100644
--- a/docs/content/en/functions/i18n.md
+++ b/docs/content/en/functions/i18n.md
@@ -18,7 +18,7 @@ deprecated: false
 aliases: []
 ---
 
-This translates a piece of content based on your `i18n/en-US.yaml` (and similar) files. You can use the [go-i18n](https://github.com/nicksnyder/go-i18n) tools to manage your translations. The translations can exist in both the theme and at the root of your repository.
+This translates a piece of content based on your `i18n/en-US.toml` files. You can use the [go-i18n](https://github.com/nicksnyder/go-i18n) tools to manage your translations. The translations can exist in both the theme and at the root of your repository.
 
 ```
 {{ i18n "translation_id" }}
@@ -28,6 +28,27 @@ This translates a piece of content based on your `i18n/en-US.yaml` (and similar)
 `T` is an alias to `i18n`. E.g. `{{ T "translation_id" }}`.
 {{% /note %}}
 
+### Query a flexible translation with variables
+
+Often you will want to use the page variables in the translation strings. To do so, pass the `.` context when calling `i18n`:
+
+```
+{{ i18n "wordCount" . }}
+```
+
+The function will pass the `.` context to the `"wordCount"` id:
+
+{{< code-toggle file="i18n/en-US" >}}
+[wordCount]
+other = "This article has {{ .WordCount }} words."
+{{< /code-toggle >}}
+
+Assume `.WordCount` in the context has value is 101. The result will be:
+
+```
+This article has 101 words.
+```
+
 For more information about string translations, see [Translation of Strings in Multilingual Mode][multistrings].
 
 [multistrings]: /content-management/multilingual/#translation-of-strings
diff --git a/docs/content/en/functions/images/index.md b/docs/content/en/functions/images/index.md
index 92c6ff0da..7dd5843ee 100644
--- a/docs/content/en/functions/images/index.md
+++ b/docs/content/en/functions/images/index.md
@@ -218,6 +218,8 @@ Also see the [Filter Method](/content-management/image-processing/#filter).
 
 Parses the image and returns the height, width, and color model.
 
+The `imageConfig` function takes a single parameter, a file path (_string_) relative to the _project's root directory_, with or without a leading slash.
+
 {{% funcsig %}}
 images.ImageConfig PATH
 {{% /funcsig %}}
diff --git a/docs/content/en/functions/slice.md b/docs/content/en/functions/slice.md
index 0710d5e40..24b717128 100644
--- a/docs/content/en/functions/slice.md
+++ b/docs/content/en/functions/slice.md
@@ -23,7 +23,9 @@ toc: false
 One use case is the concatenation of elements in combination with the [`delimit` function][]:
 
 {{< code file="slice.html" >}}
-{{ delimit (slice "foo" "bar" "buzz") ", " }}
+{{ $sliceOfStrings := slice "foo" "bar" "buzz" }}
+<!-- returns the slice [ "foo", "bar", "buzz"] -->
+{{ delimit ($sliceOfStrings) ", " }}
 <!-- returns the string "foo, bar, buzz" -->
 {{< /code >}}
 
diff --git a/docs/content/en/functions/union.md b/docs/content/en/functions/union.md
index 459e3620d..465abcdd8 100644
--- a/docs/content/en/functions/union.md
+++ b/docs/content/en/functions/union.md
@@ -40,8 +40,8 @@ This is also very useful to use as `OR` filters when combined with where:
 
 ```
 {{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
-{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
-{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
+{{ $pages = $pages | union (where .Site.RegularPages "Params.pinned" true) }}
+{{ $pages = $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
 ```
 
 The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page params.
diff --git a/docs/content/en/getting-started/configuration.md b/docs/content/en/getting-started/configuration.md
index 9393e4534..91279712a 100644
--- a/docs/content/en/getting-started/configuration.md
+++ b/docs/content/en/getting-started/configuration.md
@@ -4,7 +4,6 @@ linktitle: Configuration
 description: How to configure your Hugo site.
 date: 2013-07-01
 publishdate: 2017-01-02
-lastmod: 2017-03-05
 categories: [getting started,fundamentals]
 keywords: [configuration,toml,yaml,json]
 menu:
@@ -18,7 +17,6 @@ aliases: [/overview/source-directory/,/overview/configuration/]
 toc: true
 ---
 
-
 ## Configuration File
 
 Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the
@@ -77,6 +75,27 @@ foo = "bar"
 ```
 
 Considering the structure above, when running `hugo --environment staging`, Hugo will use every settings from `config/_default` and merge `staging`'s on top of those.
+
+Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify `googleAnalytics = "G-XXXXXXXX"` in `config.toml`. Now consider the following scenario:
+- You don't want the Analytics code to be loaded in development i.e. in your `localhost`
+- You want to use separate googleAnalytics IDs for your production & staging environments (say):
+  - `G-PPPPPPPP` for production
+  - `G-SSSSSSSS` for staging
+
+This is how you need to configure your `config.toml` files considering the above scenario:
+1. In `_default/config.toml` you don't need to mention `googleAnalytics` parameter at all. This ensures that no Google Analytics code is loaded in your development server i.e. when you run `hugo serve`. This works since, by default Hugo sets `Environment=development` when you run `hugo serve` which uses the config files from `_default` folder
+2. In `production/config.toml` you just need to have one line:
+
+    ```googleAnalytics = "G-PPPPPPPP"```
+
+    You don't need to mention all other parameters like `title`, `baseURL`, `theme` etc. again in this config file. You need to mention only those parameters which are different or new for the production environment. This is due to the fact that Hugo is going to __merge__ this on top of `_default/config.toml`. Now when you run `hugo` (build command), by default hugo sets `Environment=production`, so the `G-PPPPPPPP` analytics code will be there in your production website
+3. Similarly in `staging/config.toml` you just need to have one line:
+
+    ```googleAnalytics = "G-SSSSSSSS"```
+    
+    Now you need to tell Hugo that you are using the staging environment. So your build command should be `hugo --environment staging` which will load the `G-SSSSSSSS` analytics code in your staging website
+
+
 {{% note %}}
 Default environments are __development__ with `hugo server` and __production__ with `hugo`.
 {{%/ note %}}
@@ -149,7 +168,7 @@ See [Configure File Caches](#configure-file-caches)
 
 {{< new-in "0.86.0" >}}
 
-Pass down down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).
+Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).
 
 ### canonifyURLs
 
@@ -271,7 +290,10 @@ See [Image Processing Config](/content-management/image-processing/#imaging-conf
 
 **Default value:**  ""
 
-A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). The internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml) populates its `<language>` element with this value. The value is not used elsewhere.
+A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate:
+
+- The `<language>` element in the internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml)
+- The `lang` attribute of the `<html>` element in the internal [alias template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html)
 
 ### languages
 
diff --git a/docs/content/en/getting-started/directory-structure.md b/docs/content/en/getting-started/directory-structure.md
index 3fa66d4c5..c523219c2 100644
--- a/docs/content/en/getting-started/directory-structure.md
+++ b/docs/content/en/getting-started/directory-structure.md
@@ -31,6 +31,7 @@ Running the `hugo new site` generator from the command line will create a direct
 ├── content
 ├── data
 ├── layouts
+├── public
 ├── static
 └── themes
 ```
@@ -45,7 +46,7 @@ The following is a high-level overview of each of the directories with links to
 By default, Hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well.
 
 [`assets`][]
-: Stores all the files which need be processed by [Hugo Pipes]({{< ref "/hugo-pipes" >}}). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory. Note: assets directory is not created by default.
+: Stores all the files which need be processed by [Hugo Pipes](/hugo-pipes/). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory. Note: assets directory is not created by default.
 
 [`config`](/getting-started/configuration/)
 : Hugo ships with a large number of [configuration directives][].
@@ -71,11 +72,11 @@ used by Hugo when generating your website. You can write these files in YAML, JS
 From **Hugo 0.31** you can have multiple static directories.
 {{% /note %}}
 
-resources
+[`resources`][]
 : Caches some files to speed up generation. Can be also used by template authors to distribute built SASS files, so you don't have to have the preprocessor installed. Note: resources directory is not created by default.
 
-
 [archetypes]: /content-management/archetypes/
+[`assets`]: /hugo-pipes/introduction#asset-directory/
 [configuration directives]: /getting-started/configuration/#all-configuration-settings
 [`content`]: /content-management/organization/
 [content section]: /content-management/sections/
@@ -84,6 +85,7 @@ resources
 [homepage]: /templates/homepage/
 [`layouts`]: /templates/
 [`static`]: /content-management/static-files/
+[`resources`]: /getting-started/configuration/#configure-file-caches
 [lists]: /templates/list/
 [pagevars]: /variables/page/
 [partials]: /templates/partials/
@@ -93,4 +95,3 @@ resources
 [taxonomies]: /content-management/taxonomies/
 [taxonomy templates]: /templates/taxonomy-templates/
 [types]: /content-management/types/
-[`assets`]: {{< ref "/hugo-pipes/introduction#asset-directory" >}}
diff --git a/docs/content/en/getting-started/external-learning-resources/index.md b/docs/content/en/getting-started/external-learning-resources/index.md
index 349d7e29d..feb7cbb50 100644
--- a/docs/content/en/getting-started/external-learning-resources/index.md
+++ b/docs/content/en/getting-started/external-learning-resources/index.md