mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-15 19:24:38 -04:00
Remove lookup order table from output formats page
This commit is contained in:
Joe Mooring
GitHub
parent
bc88706573
commit
99227dd187
@ -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.
|
||||
|
||||
@ -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"]
|
||||
{{</ 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`:
|
||||
|
||||
@ -172,7 +168,7 @@ 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 -}}
|
||||
{{ 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" . }}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user