Merge commit '13e64d72763bf8d6d92d4cdfc15ed45ee9debfab'

48 files changed, 556 insertions, 340 deletions

diff --git a/docs/content/en/about/hugo-and-gdpr.md b/docs/content/en/about/hugo-and-gdpr.md
index 15352ae7c..e193e1838 100644
--- a/docs/content/en/about/hugo-and-gdpr.md
+++ b/docs/content/en/about/hugo-and-gdpr.md
@@ -28,6 +28,7 @@ toc: true
  Note that:
 
  * These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings.
+ * These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
  * We will continue this work and improve this further in future Hugo versions.
 
 ## All Privacy Settings
diff --git a/docs/content/en/content-management/archetypes.md b/docs/content/en/content-management/archetypes.md
index 904ca8c31..ff4a2d783 100644
--- a/docs/content/en/content-management/archetypes.md
+++ b/docs/content/en/content-management/archetypes.md
@@ -35,7 +35,7 @@ The above will create a new content file in `content/posts/my-first-post.md` usi
 3. `themes/my-theme/archetypes/posts.md`
 4. `themes/my-theme/archetypes/default.md`
 
-The last two list items is only applicable if you use a theme and it uses the `my-theme` theme name as an example.
+The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example.
 
 ## Create a New Archetype Template
 
diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md
index 268dc4c0e..17914ba2c 100644
--- a/docs/content/en/content-management/comments.md
+++ b/docs/content/en/content-management/comments.md
@@ -59,7 +59,7 @@ There are a few alternatives to commenting on static sites for those who do not
 * [Muut](http://muut.com/)
 * [isso](http://posativ.org/isso/) (Self-hosted, Python)
     * [Tutorial on Implementing Isso with Hugo][issotutorial]
-
+* [Utterances](https://utteranc.es/) (Open source, Github comments widget built on Github issues)
 
 <!-- I don't think this is worth including in the documentation since it seems that Steve is no longer supporting or developing this project. rdwatters - 2017-02-29.-->
 <!-- * [Kaiju](https://github.com/spf13/kaiju) -->
diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md
index ab9fdd781..f7a466c3c 100644
--- a/docs/content/en/content-management/formats.md
+++ b/docs/content/en/content-management/formats.md
@@ -240,7 +240,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
 [mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
 [mdguide]: https://www.markdownguide.org/
 [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
 [mmarkgh]: https://github.com/miekg/mmark/wiki/Syntax
 [org]: http://orgmode.org/
diff --git a/docs/content/en/content-management/menus.md b/docs/content/en/content-management/menus.md
index 4278b03be..bc48c82e7 100644
--- a/docs/content/en/content-management/menus.md
+++ b/docs/content/en/content-management/menus.md
@@ -80,7 +80,7 @@ You can also add entries to menus that aren’t attached to a piece of content.
 
 Here’s an example snippet pulled from a configuration file:
 
-{{< code-toggle file="config.toml" >}}
+{{< code-toggle file="config" >}}
 [[menu.main]]
     name = "about hugo"
     pre = "<i class='fa fa-heart'></i>"
@@ -90,6 +90,7 @@ Here’s an example snippet pulled from a configuration file:
 [[menu.main]]
     name = "getting started"
     pre = "<i class='fa fa-road'></i>"
+    post = "<span class='alert'>New!</span>"
     weight = -100
     url = "/getting-started/"
 {{< /code-toggle >}}
diff --git a/docs/content/en/content-management/related.md b/docs/content/en/content-management/related.md
index 9a4c77d40..636e95970 100644
--- a/docs/content/en/content-management/related.md
+++ b/docs/content/en/content-management/related.md
@@ -14,13 +14,13 @@ aliases: [/content/related/,/related/]
 toc: true
 ---
 
-{{% note %}}
-We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock).
-{{% /note %}}
+
+Hugo uses a set of factors to identify a page's related content based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content). 
 
 ## List Related Content
 
-To list up to 5 related pages is as simple as including something similar to this partial in your single page template:
+
+To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template: 
 
 {{< code file="layouts/partials/related.html" >}}
 {{ $related := .Site.RegularPages.Related . | first 5 }}
@@ -34,67 +34,62 @@ To list up to 5 related pages is as simple as including something similar to thi
 {{ end }}
 {{< /code >}}
 
+### Methods
 
-{{% note %}}
-Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
-{{% /note %}}
+Here is the list of "Related" methods available on a page collection such `.RegularPages`.
 
-The full set of methods available on the page lists can be seen in this Go interface:
+#### .Related PAGE
+Returns a collection of pages related the given one.
 
-```go
-// A PageGenealogist finds related pages in a page collection. This interface is implemented
-// by Pages and PageGroup, which makes it available as `{{ .RegularPages.Related . }}` etc.
-type PageGenealogist interface {
+```
+{{ $related := .RegularPages.Related . }}
+```
 
-	// Template example:
-	// {{ $related := .RegularPages.Related . }}
-	Related(doc related.Document) (Pages, error)
+#### .RelatedIndices PAGE INDICE1 [INDICE2 ...]
+Returns a collection of pages related to a given one restricted to a list of indices.
 
-	// Template example:
-	// {{ $related := .RegularPages.RelatedIndices . "tags" "date" }}
-	RelatedIndices(doc related.Document, indices ...interface{}) (Pages, error)
+```
+{{ $related := .RegularPages.RelatedIndices . "tags" "date" }}
+```
+
+#### .RelatedTo KEYVALS [KEYVALS2 ...]
+Returns a collection of pages related together by a set of indices and their match. 
 
-	// Template example:
-	// {{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks")  ( keyVals "date" .Date ) }}
-	RelatedTo(args ...types.KeyValues) (Pages, error)
-}
+In order to build those set and pass them as argument, one must use the `keyVals` function where the first agrument would be the `indice` and the consective ones its potential `matches`.
+
+```
+{{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks")  ( keyVals "date" .Date ) }}
 ```
+
+{{% note %}}
+Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
+{{% /note %}}
+
 ## Configure Related Content
 Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed.
 
+### Default configuration
+
+Without any `related` configuration set on the project, Hugo's Related Content methods will use the following.
+
+```yaml
+related:
+  threshold: 80
+  includeNewer: false
+  toLower: false
+  indices:
+  - name: keywords
+    weight: 100
+  - name: date
+    weight: 10
+```
+
+Custom configuration should be set using the same syntax.
+
 {{% note %}}
 If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest  from the Hugo defaults.
 {{% /note %}}
 
-Below is a sample `config.toml` section:
-
-```
-[related]
-
-# Only include matches with rank >= threshold. This is a normalized rank between 0 and 100.
-threshold = 80
-
-# To get stable "See also" sections we, by default, exclude newer related pages.
-includeNewer = false
-
-# Will lower case keywords in both queries and in the indexes.
-toLower = false
-
-[[related.indices]]
-name = "keywords"
-weight = 150
-[[related.indices]]
-name  = "author"
-toLower = true
-weight = 30
-[[related.indices]]
-name  = "tags"
-weight = 100
-[[related.indices]]
-name  = "date"
-weight = 10
-pattern = "2006"
-```
 ### Top Level Config Options
 
 threshold
@@ -135,9 +130,6 @@ He should now be able to add an improved version of that "Related Content" secti
 * If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before.
 * Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites.
 
-
-
-
-
-
-
+{{% note %}}
+We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock).
+{{% /note %}}
diff --git a/docs/content/en/content-management/summaries.md b/docs/content/en/content-management/summaries.md
index 0f8939377..63d64aa3c 100644
--- a/docs/content/en/content-management/summaries.md
+++ b/docs/content/en/content-management/summaries.md
@@ -21,32 +21,40 @@ With the use of the `.Summary` [page variable][pagevariables], Hugo generates su
 
 ## Summary Splitting Options
 
-* Hugo-defined Summary Split
-* User-defined Summary Split
+* Automatic Summary Split
+* Manual Summary Split
 
 It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables].
 
-### Hugo-defined: Automatic Summary Splitting
+### Automatic Summary Splitting
 
-By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. Taking the Hugo-defined approach to summaries may save time, but it has pros and cons:
+By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/).
 
-* **Pros:** Automatic, no additional work on your part.
-* **Cons:** All HTML tags are stripped from the summary, and the first 70 words, whether they belong to a heading or to different paragraphs, are all put into one paragraph.
+{{% note %}}
+You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`.
+{{% /note %}}
 
 {{% note %}}
-The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive white space characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in you [site configuration](/getting-started/configuration/).
+The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/).
 {{% /note %}}
 
-### User-defined: Manual Summary Splitting
+### Manual Summary Splitting
+
+Alternatively, you may add the <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider where you want to split the article. 
 
-Alternatively, you may add the <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider where you want to split the article. For [org content][org], use `# more` where you want to split the article. Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact.
+For [Org mode content][org], use `# more` where you want to split the article. 
+
+Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact.
 
 {{% note "Summary Divider"%}}
 The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature.
 {{% /note %}}
 
-* Pros: Freedom, precision, and improved rendering.  All HTML tags and formatting are preserved.
-* Cons: Extra work for content authors, since they need to remember to type <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
+Pros
+: Freedom, precision, and improved rendering.  All HTML tags and formatting are preserved.
+
+Cons
+: Extra work for content authors, since they need to remember to type <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
 
 {{% warning "Be Precise with the Summary Divider" %}}
 Be careful to enter <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> exactly; i.e., all lowercase and with no whitespace.
diff --git a/docs/content/en/contribute/development.md b/docs/content/en/contribute/development.md
index be2ca4a2b..e9e1cd10f 100644
--- a/docs/content/en/contribute/development.md
+++ b/docs/content/en/contribute/development.md
@@ -15,7 +15,6 @@ menu:
 weight: 10
 sections_weight: 10
 draft: false
-aliases: [/contribute/development/]
 toc: true
 ---
 
diff --git a/docs/content/en/contribute/documentation.md b/docs/content/en/contribute/documentation.md
index e8603d432..7b198a4ca 100644
--- a/docs/content/en/contribute/documentation.md
+++ b/docs/content/en/contribute/documentation.md
@@ -94,15 +94,15 @@ Code blocks are crucial for providing examples of Hugo's new features to end use
 
 ### Standard Syntax
 
-Across all pages on the Hugo docs, the typical triple-back-tick markdown syntax is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard GitHub-flavored markdown. The Hugo docs use a version of [highlight.js](https://highlightjs.org/) with a specific set of languages.
+Across many pages on the Hugo docs, the typical triple-back-tick markdown syntax (```` ``` ````) is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard GitHub-flavored markdown. The Hugo docs use a version of [highlight.js](https://highlightjs.org/) with a specific set of languages.
 
 Your options for languages are `xml`/`html`, `go`/`golang`, `md`/`markdown`/`mkd`, `handlebars`, `apache`, `toml`, `yaml`, `json`, `css`, `asciidoc`, `ruby`, `powershell`/`ps`, `scss`, `sh`/`zsh`/`bash`/`git`, `http`/`https`, and `javascript`/`js`.
 
-```
+````
 ```
 <h1>Hello world!</h1>
 ```
-```
+````
 
 ### Code Block Shortcode
 
@@ -118,14 +118,13 @@ With the `code` shortcodes, *you must include triple back ticks and a language d
 
 ```
 {{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
-```
 A whole bunch of coding going on up in here!
-```
 {{%/* /code */%}}
 ```
 
 The following are the arguments passed into `code`:
 
+
 ***`file`***
 : the only *required* argument. `file` is needed for styling but also plays an important role in helping users create a mental model around Hugo's directory structure. Visually, this will be displayed as text in the top left of the code block.
 
@@ -194,10 +193,8 @@ The `output` shortcode is almost identical to the `code` shortcode but only take
 
 ```
 {{%/* output file="post/my-first-post/index.html" */%}}
-```
 <h1>This is my First Hugo Blog Post</h1>
 <p>I am excited to be using Hugo.</p>
-```
 {{%/* /output */%}}
 ```
 
diff --git a/docs/content/en/functions/GetPage.md b/docs/content/en/functions/GetPage.md
index 2d9de4d7a..366d1f093 100644
--- a/docs/content/en/functions/GetPage.md
+++ b/docs/content/en/functions/GetPage.md
@@ -31,7 +31,7 @@ aliases: []
 
 This method wil return `nil` when no page could be found, so the above will not print anything if the blog section is not found.
 
-To fund a regular page in the blog section::
+To find a regular page in the blog section::
 
 ```go-html-template
 {{ with .Site.GetPage "/blog/my-post.md" }}{{ .Title }}{{ end }}
diff --git a/docs/content/en/functions/default.md b/docs/content/en/functions/default.md
index 1b5a9fb6f..18f7b7d33 100644
--- a/docs/content/en/functions/default.md
+++ b/docs/content/en/functions/default.md
@@ -22,7 +22,7 @@ aliases: []
 needsexamples: false
 ---
 
-`default` checks whether a given value is set and returns a default value if it is not. *Set* in this context means different things depending on date type:
+`default` checks whether a given value is set and returns a default value if it is not. *Set* in this context means different things depending on the data type:
 
 * non-zero for numeric types and times
 * non-zero length for strings, arrays, slices, and maps
diff --git a/docs/content/en/functions/intersect.md b/docs/content/en/functions/intersect.md
index a607ff217..6d2efacbc 100644
--- a/docs/content/en/functions/intersect.md
+++ b/docs/content/en/functions/intersect.md
@@ -19,27 +19,7 @@ deprecated: false
 aliases: []
 ---
 
-The elements supported are strings, integers, and floats (only float64).
-
-A useful example of `intersect` functionality is a "related posts" block. `isset` allows us to create a list of links to other posts that have tags that intersect with the tags in the current post.
-
-The following is an example of a "related posts" [partial template][partials] that could be added to a [single page template][single]:
-
-{{< code file="layouts/partials/related-posts.html" download="related-posts.html" >}}
-<ul>
-{{ $page_link := .Permalink }}
-{{ $tags := .Params.tags }}
-{{ range .Site.Pages }}
-    {{ $page := . }}
-    {{ $has_common_tags := intersect $tags .Params.tags | len | lt 0 }}
-    {{ if and $has_common_tags (ne $page_link $page.Permalink) }}