TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-15 03:04:37 -04:00
Code Issues Packages Projects Releases Wiki Activity

Remove lookup order table from output formats page

Browse Source
This commit is contained in:
Joe Mooring 2023-08-15 12:59:34 -07:00 committed by GitHub
parent bc88706573
commit 99227dd187
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 23 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
content/en/templates/output-formats.md
View File

@ -16,7 +16,7 @@ This page describes how to properly configure your site with the media types and
## Media types ## 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: 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"] suffixes = ["htm"]
[outputFormats] [outputFormats]
[outputFormats.HTML] [outputFormats.html]
mediaType = "text/html" mediaType = "text/html"
{{</ code-toggle >}} {{</ 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" >}} {{< 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`. - 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. - 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. - 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. 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" >}} {{< code-toggle file="hugo" >}}
[outputs] [outputs]
home = ["HTML", "AMP", "RSS"] home = ["html", "amp", "rss"]
page = ["HTML"] page = ["html"]
{{</ code-toggle >}} {{</ code-toggle >}}
Note that in the above examples, the _output formats_ for `section`, 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].
* 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 `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 following is an example of front matter in a content file that defines output formats for the rendered `Page`: 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 ```go-html-template
{{ range .AlternativeOutputFormats -}} {{ range .AlternativeOutputFormats -}}
<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}"> <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
{{ end -}} {{ end }}
``` ```
## Link to output formats ## Link to output formats
@ -181,10 +177,10 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an
__from `single.json.json`:__ __from `single.json.json`:__
```go-html-template ```go-html-template
{{ .RelPermalink }} > /that-page/ {{ .RelPermalink }} → /that-page/
{{ with .OutputFormats.Get "json" -}} {{ with .OutputFormats.Get "json" }}
{{ .RelPermalink }} > /that-page/index.json {{ .RelPermalink }} → /that-page/index.json
{{- end }} {{ 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. 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:** **Same template file as above with json output format's `permalinkable` set to true:**
```go-html-template ```go-html-template
{{ .RelPermalink }} > /that-page/index.json {{ .RelPermalink }} → /that-page/index.json
{{ with .OutputFormats.Get "html" -}} {{ with .OutputFormats.Get "html" }}
{{ .RelPermalink }} > /that-page/ {{ .RelPermalink }} → /that-page/
{{- end }} {{ end }}
``` ```
From content files, you can use the [`ref` or `relref` shortcodes](/content-management/shortcodes/#ref-and-relref): 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 ## 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 %}} For example, to generate a JSON file for the home page, the template with highest specificity is `layouts/index.json.json`.
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" >}}
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. 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] [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 ```go-html-template
{{ partial "mytextpartial.csv" . }} {{ partial "mytextpartial.csv" . }}