Merge commit 'ec920363cdeb687c8bcac9c242767d366fb058cb'

5 files changed, 57 insertions, 76 deletions

diff --git a/docs/content/en/templates/404.md b/docs/content/en/templates/404.md
index 1b82e9ebf..a2d06cf81 100644
--- a/docs/content/en/templates/404.md
+++ b/docs/content/en/templates/404.md
@@ -51,7 +51,7 @@ Your 404.html file can be set to load automatically when a visitor enters a mist
 * Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. [Details here](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
 * Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.
 * Amazon CloudFront. You can specify the page in the Error Pages section in the CloudFront Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html)
-* Caddy Server. Using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors)
+* Caddy Server. Use the `handle_errors` directive to specify error pages for one or more status codes. [Details here](https://caddyserver.com/docs/caddyfile/directives/handle_errors)
 * Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404)
 * Azure Static website. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [More details are available in the Static website documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website).
 
diff --git a/docs/content/en/templates/ordering-and-grouping.md b/docs/content/en/templates/ordering-and-grouping.md
index a4f238fdf..f1634c7d8 100644
--- a/docs/content/en/templates/ordering-and-grouping.md
+++ b/docs/content/en/templates/ordering-and-grouping.md
@@ -1,5 +1,5 @@
 ---
-title: Ordere and Grouping Hugo Lists
+title: Ordering and Grouping Hugo Lists
 linktitle: List Ordering and Grouping
 description: You can group or order your content in both your templating and content front matter.
 date: 2017-02-01
@@ -19,7 +19,7 @@ toc: true
 notes: This was originally going to be a separate page on the new docs site but it now makes more sense to keep everything within the templates/lists page. - rdwatters, 2017-03-12.
 ---
 
-In Hugo, A list template is any template that will be used to render multiple pieces of content in a single HTML page.
+In Hugo, a list template is any template that will be used to render multiple pieces of content in a single HTML page.
 
 ## Example List Templates
 
diff --git a/docs/content/en/templates/partials.md b/docs/content/en/templates/partials.md
index 2d1e9edf2..56a676d7e 100644
--- a/docs/content/en/templates/partials.md
+++ b/docs/content/en/templates/partials.md
@@ -78,7 +78,7 @@ This means the partial will *only* be able to access those variables. The partia
 
 ## 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.
+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 _at the end of the partial_.
 
 ### Example GetFeatured
 
diff --git a/docs/content/en/templates/render-hooks.md b/docs/content/en/templates/render-hooks.md
index 57c2efa06..8f1a55c2f 100644
--- a/docs/content/en/templates/render-hooks.md
+++ b/docs/content/en/templates/render-hooks.md
@@ -25,7 +25,7 @@ The hook kinds currently supported are:
 * `image`
 * `link`
 * `heading` {{< new-in "0.71.0" >}}
-* `codeblock`{{< new-in "0.83.0" >}}
+* `codeblock`{{< new-in "0.93.0" >}}
 
 You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this:
 
diff --git a/docs/content/en/templates/sitemap-template.md b/docs/content/en/templates/sitemap-template.md
index dee28fc3b..9fc817020 100644
--- a/docs/content/en/templates/sitemap-template.md
+++ b/docs/content/en/templates/sitemap-template.md
@@ -1,10 +1,7 @@
 ---
-title: Sitemap Template
-# linktitle: Sitemap
-description: Hugo ships with a built-in template file observing the v0.9 of the Sitemap Protocol, but you can override this template if needed.
+title: Sitemap Templates
+description: Hugo provides built-in sitemap templates.
 date: 2017-02-01
-publishdate: 2017-02-01
-lastmod: 2017-02-01
 categories: [templates]
 keywords: [sitemap, xml, templates]
 menu:
@@ -15,92 +12,76 @@ weight: 160
 sections_weight: 160
 draft: false
 aliases: [/layout/sitemap/,/templates/sitemap/]
-toc: false
+toc: true
 ---
 
-A single Sitemap template is used to generate the `sitemap.xml` file.
-Hugo automatically comes with this template file. *No work is needed on
-the users' part unless they want to customize `sitemap.xml`.*
+## Overview
 
-A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use in this template along with Sitemap-specific ones:
+Hugo's built-in sitemap templates conform to v0.9 of the [sitemap protocol].
 
-`.Sitemap.ChangeFreq`
-: The page change frequency
+With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemap.xml] template.
 
-`.Sitemap.Priority`
-: The priority of the page
+With a multilingual project, Hugo generates:
 
-`.Sitemap.Filename`
-: The sitemap filename
+- A sitemap.xml file in the root of each site (language) using the built-in [sitemap.xml] template
+- A sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemapindex.xml] template
 
-If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo.
+## Configuration
 
-## Sitemap Templates
+Set the default values for [change frequency] and [priority], and the name of the generated file, in your site configuration.
 
-Hugo has built-on Sitemap templates, but you can provide your own if needed, in either `layouts/sitemap.xml` or `layouts/_default/sitemap.xml`.
+{{< code-toggle file="config" >}}
+[sitemap]
+  changefreq = 'monthly'
+  filename = 'sitemap.xml'
+  priority = 0.5
+{{</ code-toggle >}}
 
-For multilingual sites, we also create a Sitemap index. You can provide a custom layout for that in either `layouts/sitemapindex.xml` or `layouts/_default/sitemapindex.xml`.
+changefreq
+: How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is `""` (change frequency omitted from rendered sitemap).
 
-## Hugo’s sitemap.xml
+filename
+: The name of the generated file. Default is `sitemap.xml`.
 
-This template respects the version 0.9 of the [Sitemap Protocol](https://www.sitemaps.org/protocol.html).
+priority
+: The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is `-1` (priority omitted from rendered sitemap).
 
-```xml
-{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }}
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
-  xmlns:xhtml="http://www.w3.org/1999/xhtml">
-  {{ range .Data.Pages }}
-  <url>
-    <loc>{{ .Permalink }}</loc>{{ if not .Lastmod.IsZero }}
-    <lastmod>{{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>{{ end }}{{ with .Sitemap.ChangeFreq }}
-    <changefreq>{{ . }}</changefreq>{{ end }}{{ if ge .Sitemap.Priority 0.0 }}
-    <priority>{{ .Sitemap.Priority }}</priority>{{ end }}{{ if .IsTranslated }}{{ range .Translations }}
-    <xhtml:link
-                rel="alternate"
-                hreflang="{{ .Lang }}"
-                href="{{ .Permalink }}"
-                />{{ end }}
-    <xhtml:link
-                rel="alternate"
-                hreflang="{{ .Lang }}"
-                href="{{ .Permalink }}"
-                />{{ end }}
-  </url>
-  {{ end }}
-</urlset>
-```
+## Override Default Values
 
-## Hugo's sitemapindex.xml
+Override the default values for a given page in front matter.
 
-This is used to create a Sitemap index in multilingual mode:
+{{< code-toggle file="news.md" fm=true >}}
+title = 'News'
+[sitemap]
+  changefreq = 'weekly'
+  priority = 0.8
+{{</ code-toggle >}}
 
-```xml
-{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }}
-<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-	{{ range . }}
-	<sitemap>
-	   	<loc>{{ .SitemapAbsURL }}</loc>
-		{{ if not .LastChange.IsZero }}
-	   	<lastmod>{{ .LastChange.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</lastmod>
-		{{ end }}
-	</sitemap>
-	{{ end }}
-</sitemapindex>
-```
+## Override Built-in Templates
 
-## Configure `sitemap.xml`
+To override the built-in sitemap.xml template, create a new file in either of these locations:
 
-Defaults for `<changefreq>`, `<priority>` and `filename` values can be set in the site's config file, e.g.:
+- layouts/sitemap.xml
+- layouts/_default/sitemap.xml
 
-{{< code-toggle file="config" >}}
-[sitemap]
-  changefreq = "monthly"
-  priority = 0.5
-  filename = "sitemap.xml"
-{{</ code-toggle >}}
+When ranging through the page collection, access the _change frequency_ and _priority_ with `.Sitemap.ChangeFreq` and `.Sitemap.Priority` respectively.
+
+To override the built-in sitemapindex.xml template, create a new file in either of these locations:
 
-The same fields can be specified in an individual content file's front matter in order to override the value assigned to that piece of content at render time.
+- layouts/sitemapindex.xml
+- layouts/_default/sitemapindex.xml
 
+## Disable Sitemap Generation
 
+You may disable sitemap generation in your site configuration:
+
+{{< code-toggle file="config" >}}
+disableKinds = ['sitemap']
+{{</ code-toggle >}}
 
-[pagevars]: /variables/page/
+[`publishDir`]: {{< relref "getting-started/configuration#publishdir" >}}
+[change frequency]: <https://www.sitemaps.org/protocol.html#changefreqdef>
+[priority]: <https://www.sitemaps.org/protocol.html#priority>
+[sitemap protocol]: <https://www.sitemaps.org/protocol.html>
+[sitemap.xml]: <https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/sitemap.xml>
+[sitemapindex.xml]: <https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/sitemapindex.xml>