Merge commit '77b976dd92b4f66657d83d875aef0c617df492d9'

1 files changed, 24 insertions, 43 deletions

diff --git a/docs/content/en/templates/output-formats.md b/docs/content/en/templates/output-formats.md
index d1f5f3bfe..5f2abdc2a 100644
--- a/docs/content/en/templates/output-formats.md
+++ b/docs/content/en/templates/output-formats.md
@@ -16,7 +16,7 @@ This page describes how to properly configure your site with the media types and
 
 ## Media types
 
-A [media type] (also known as _MIME type_ and _content type_) is a two-part identifier for file formats and format contents transmitted on the internet.
+A [media type] (formerly known as a MIME type) is a two-part identifier for file formats and format contents transmitted on the internet.
 
 This is the full set of built-in media types in Hugo:
 
@@ -49,7 +49,7 @@ The above example adds one new media type, `text/enriched`, and changes the suff
     suffixes = ["htm"]
 
 [outputFormats]
-  [outputFormats.HTML]
+  [outputFormats.html]
     mediaType = "text/html"
 {{</ code-toggle >}}
 
@@ -63,9 +63,9 @@ This is the full set of Hugo's built-in output formats:
 
 {{< datatable "config" "outputFormats" "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.
-- You can define new output formats or redefine built-in output formats; e.g., if you want to put `AMP` pages in a different path.
+- 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 a defined media type.
+- You can define new output formats or redefine built-in output formats; e.g., if you want to put `amp` pages in a different path.
 
 To add or modify an output format, define it in an `outputFormats` section in your site's [configuration file](/getting-started/configuration/), either for all sites or for a given language.
 
@@ -129,13 +129,7 @@ system.
 Every `Page` has a [`Kind`][page_kinds] attribute, and the default Output
 Formats are set based on that.
 
-| Kind       | Default Output Formats |
-| ---------- | ---------------------- |
-| `page`     | HTML                   |
-| `home`     | HTML, RSS              |
-| `section`  | HTML, RSS              |
-| `taxonomy` | HTML, RSS              |
-| `term`     | HTML, RSS              |
+{{< code-toggle config="outputs" />}}
 
 ### Customizing output formats
 
@@ -147,19 +141,15 @@ Example from site configuration file:
 
 {{< code-toggle file="hugo" >}}
 [outputs]
-  home = ["HTML", "AMP", "RSS"]
-  page = ["HTML"]
+  home = ["html", "amp", "rss"]
+  page = ["html"]
 {{</ code-toggle >}}
 
 Note that in the above examples, the _output formats_ for `section`,
-`taxonomy` and `term` will stay at their default value `["HTML", "RSS"]`.
+`taxonomy` and `term` will stay at their default value `['html','rss']`.
 
-{{% page-kinds %}}
-
-* The `outputs` definition is per [`Page` `Kind`][page_kinds] (`page`, `home`, `section`, `taxonomy`, or `term`).
-* The names (e.g. `HTML`, `AMP`) used must match the `Name` of a defined *Output Format*.
-  * These names are case insensitive.
-* These can be overridden per `Page` in the front matter of content files.
+* The `outputs` definition is per page [`Kind`][page_kinds].
+* The names (e.g. `html`, `amp`) must match the `name` of a defined output format, and can be overridden per page in front matter.
 
 The following is an example of front matter in a content file that defines output formats for the rendered `Page`:
 
@@ -177,8 +167,8 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an
 
 ```go-html-template
 {{ range .AlternativeOutputFormats -}}
-<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
-{{ end -}}
+  <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
+{{ end }}
 ```
 
 ## Link to output formats
@@ -187,10 +177,10 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an
 
 __from `single.json.json`:__
 ```go-html-template
-{{ .RelPermalink }} > /that-page/
-{{ with  .OutputFormats.Get "json" -}}
-{{ .RelPermalink }} > /that-page/index.json
-{{- end }}
+{{ .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.
@@ -198,10 +188,10 @@ In order for them to return the output format of the current template file inste
 **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 }}
+{{ .RelPermalink }} → /that-page/index.json
+{{ with  .OutputFormats.Get "html" }}
+  {{ .RelPermalink }} → /that-page/
+{{ end }}
 ```
 
 From content files, you can use the [`ref` or `relref` shortcodes](/content-management/shortcodes/#ref-and-relref):
@@ -213,18 +203,9 @@ From content files, you can use the [`ref` or `relref` shortcodes](/content-mana
 
 ## Templates for your output formats
 
-A new output format needs a corresponding template in order to render anything useful.
-
-{{% note %}}
-The key distinction for Hugo versions 0.20 and newer is that Hugo looks at an output format's `Name` and MediaType's `Suffixes` when choosing the template used to render a given `Page`.
-{{% /note %}}
-
-The following table shows examples of different output formats, the suffix used, and Hugo's respective template [lookup order]. All the examples in the table can:
-
-* Use a [base template][base].
-* Include [partial templates][partials]
+Each output format requires a corresponding template conforming to the [template lookup order](/templates/lookup-order/). Hugo considers both output format and suffix when selecting a template.
 
-{{< datatable "output" "layouts" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+For example, to generate a JSON file for the home page, the template with highest specificity is `layouts/index.json.json`.
 
 Hugo will now also detect the media type and output format of partials, if possible, and use that information to decide if the partial should be parsed as a plain text template or not.
 
@@ -234,7 +215,7 @@ Hugo will look for the name given, so you can name it whatever you want. But if
 [partial name].[OutputFormat].[suffix]
 ```
 
-The partial below is a plain text template (Output Format is `CSV`, and since this is the only output format with the suffix `csv`, we don't need to include the Output Format's `Name`):
+The partial below is a plain text template . The output format is `csv`, and since this is the only output format with the suffix `csv`, we don't need to include the output format `name`):
 
 ```go-html-template
 {{ partial "mytextpartial.csv" . }}