From 99227dd1875cc8b00ef334bfc7c5a96bc2926949 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Tue, 15 Aug 2023 12:59:34 -0700 Subject: [PATCH] Remove lookup order table from output formats page --- content/en/templates/output-formats.md | 59 ++++++++++---------------- 1 file changed, 23 insertions(+), 36 deletions(-) diff --git a/content/en/templates/output-formats.md b/content/en/templates/output-formats.md index 23b0f1696..5f2abdc2a 100644 --- a/content/en/templates/output-formats.md +++ b/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" {{}} @@ -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. @@ -141,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"] {{}} 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`: @@ -171,8 +167,8 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an ```go-html-template {{ range .AlternativeOutputFormats -}} - -{{ end -}} + +{{ end }} ``` ## Link to output formats @@ -181,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. @@ -192,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): @@ -207,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. +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. -{{% 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] - -{{< 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. @@ -228,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" . }}