diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-08-30 19:24:34 +0200 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-08-30 19:24:34 +0200 |
commit | db45dbbee8ad59c9f585db2828dcf9284220b62f (patch) | |
tree | d7cfb67244ea2558d5b6da2688f0b46ed67e8cd6 /docs/content/en/templates/output-formats.md | |
parent | e847a98db62872a72b9aa95933f1d7262a9d1c0b (diff) | |
parent | 77b976dd92b4f66657d83d875aef0c617df492d9 (diff) |
Merge commit '77b976dd92b4f66657d83d875aef0c617df492d9'
Diffstat (limited to 'docs/content/en/templates/output-formats.md')
-rw-r--r-- | docs/content/en/templates/output-formats.md | 67 |
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" . }} |