mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-25 15:58:53 +00:00
Improve description of output format template selection
This commit is contained in:
Joe Mooring
@@ -33,7 +33,7 @@ To create an empty map:
|
||||
{{ $m := dict }}
|
||||
```
|
||||
|
||||
Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.:
|
||||
Note that the `key` can be either a `string` or a `[]string`. The latter is useful to create a deeply nested structure, e.g.:
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict (slice "a" "b" "c") "value" }}
|
||||
|
||||
@@ -291,7 +291,7 @@ To remain consistent and prevent unexpected behavior, do not mix these strategie
|
||||
|
||||
###### disableKinds
|
||||
|
||||
(`string slice`) Disable rendering of the specified page [kinds](g), any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
|
||||
(`[]string`) Disable rendering of the specified page [kinds](g), any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
|
||||
|
||||
###### disableLanguages
|
||||
|
||||
@@ -337,7 +337,7 @@ See [Front matter Configuration](#configure-front-matter).
|
||||
(`bool`) Ignore the cache directory. Default is `false`.
|
||||
|
||||
###### ignoreLogs
|
||||
(`string slice`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`] and [`warnidf`].
|
||||
(`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`] and [`warnidf`].
|
||||
|
||||
[`erroridf`]: /functions/fmt/erroridf/
|
||||
[`warnidf`]: /functions/fmt/warnidf/
|
||||
@@ -474,7 +474,7 @@ content/post/hügó.md → https://example.org/post/hugo/
|
||||
|
||||
{{< new-in 0.124.0 >}}
|
||||
|
||||
(`string slice`) A list of segments to render. If not set, everything will be rendered. This is more commonly set in a CLI flag, e.g. `hugo --renderSegments segment1,segment2`. The segment names must match the names in the [segments](#configure-segments) configuration.
|
||||
(`[]string`) A list of segments to render. If not set, everything will be rendered. This is more commonly set in a CLI flag, e.g. `hugo --renderSegments segment1,segment2`. The segment names must match the names in the [segments](#configure-segments) configuration.
|
||||
|
||||
###### sectionPagesMenu
|
||||
|
||||
|
||||
@@ -161,14 +161,14 @@ lang
|
||||
: (`string`) The language code, e.g. "en". Only relevant for `content` mounts, and `static` mounts when in multihost mode.
|
||||
|
||||
includeFiles
|
||||
: (`string` or `string slice`) One or more [glob](https://github.com/gobwas/glob) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted.
|
||||
: (`string` or `[]string`) One or more [glob](https://github.com/gobwas/glob) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted.
|
||||
|
||||
The glob patterns are matched to the file names starting from the `source` root, they should have Unix styled slashes even on Windows, `/` matches the mount root and `**` can be used as a super-asterisk to match recursively down all directories, e.g `/posts/**.jpg`.
|
||||
|
||||
The search is case-insensitive.
|
||||
|
||||
excludeFiles
|
||||
: (`string` or `string slice`) One or more glob patterns matching files to exclude.
|
||||
: (`string` or `[]string`) One or more glob patterns matching files to exclude.
|
||||
|
||||
### Example
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@ This is the full set of built-in media types in Hugo:
|
||||
|
||||
{{< datatable "config" "mediaTypes" "_key" "suffixes" >}}
|
||||
|
||||
**Note:**
|
||||
Notes:
|
||||
|
||||
- It is possible to add custom media types or change the defaults; e.g., if you want to change the suffix for `text/html` to `asp`.
|
||||
- `Suffixes` are the values that will be used for URLs and file names for that media type in Hugo.
|
||||
@@ -41,7 +41,7 @@ To add or modify a media type, define it in a `mediaTypes` section in your [site
|
||||
|
||||
The above example adds one new media type, `text/enriched`, and changes the suffix for the built-in `text/html` media type.
|
||||
|
||||
**Note:** these media types are configured for **your output formats**. If you want to redefine one of Hugo's default output formats (e.g. `HTML`), you also need to redefine the media type. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`:
|
||||
These media types are configured for your output formats. If you want to redefine one of Hugo's default output formats, you also need to redefine the media type. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[mediaTypes]
|
||||
@@ -65,7 +65,8 @@ This is the full set of Hugo's built-in output formats:
|
||||
|
||||
{{< datatable "config" "outputFormats" "_key" "baseName" "isHTML" "isPlainText" "mediaType" "noUgly" "path" "permalinkable" "protocol" "rel" >}}
|
||||
|
||||
- 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 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.
|
||||
|
||||
@@ -89,10 +90,10 @@ baseName
|
||||
: (`string`) The base name of the published file. Default is `index`.
|
||||
|
||||
isHTML
|
||||
: (`bool`) If `true`, classifies the output format as HTML. Hugo uses this value to determine when to create alias redirects, when to inject the LiveReload script, etc. Default is `false`.
|
||||
: (`bool`) Whether to classify the output format as HTML. Hugo uses this value to determine when to create alias redirects, when to inject the LiveReload script, etc. Default is `false`.
|
||||
|
||||
isPlainText
|
||||
: (`bool`) If `true`, Hugo parses templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`.
|
||||
: (`bool`) Whether to parse templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`.
|
||||
|
||||
[html/template]: https://pkg.go.dev/html/template
|
||||
[text/template]: https://pkg.go.dev/text/template
|
||||
@@ -103,12 +104,12 @@ mediaType
|
||||
[media type]: https://en.wikipedia.org/wiki/Media_type
|
||||
|
||||
notAlternative
|
||||
: (`bool`) If `true`, excludes this output format from the values returned by the [`AlternativeOutputFormats`] method on a `Page` object. Default is `false`.
|
||||
: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`] method on a `Page` object. Default is `false`.
|
||||
|
||||
[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
|
||||
|
||||
noUgly
|
||||
: (`bool`) If `true`, disables ugly URLs for this output format when `uglyURLs` is `true` in your site configuration. Default is `false`.
|
||||
: (`bool`) Whether to disable ugly URLs for this output format when `uglyURLs` is `true` in your site configuration. Default is `false`.
|
||||
|
||||
path
|
||||
: (`string`) The path to the directory containing the published files, relative to the root of the publish directory.
|
||||
@@ -126,10 +127,10 @@ rel
|
||||
: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`.
|
||||
|
||||
root
|
||||
: (`bool`) If `true`, files will be published to the root of the publish directory. Default is `false`.
|
||||
: (`bool`) Whether to publish files to the root of the publish directory. Default is `false`.
|
||||
|
||||
ugly
|
||||
: (`bool`) If `true`, enables uglyURLs for this output format when `uglyURLs` is `false` in your site configuration. Default is `false`.
|
||||
: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your site configuration. Default is `false`.
|
||||
|
||||
weight
|
||||
: (`int`) When set to a non-zero value, Hugo uses the `weight` as the first criteria when sorting output formats, falling back to the name of the output format. Lighter items float to the top, while heavier items sink to the bottom. Hugo renders output formats sequentially based on the sort order.
|
||||
@@ -160,11 +161,11 @@ Example from site configuration file:
|
||||
page = ["html"]
|
||||
{{</ code-toggle >}}
|
||||
|
||||
Note that in the above examples, the _output formats_ for `section`,
|
||||
Note that in the examples above, the output formats for `section`,
|
||||
`taxonomy` and `term` will stay at their default value `['html','rss']`.
|
||||
|
||||
* The `outputs` definition is per page [`Kind`].
|
||||
* 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`].
|
||||
- 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`:
|
||||
|
||||
@@ -196,7 +197,8 @@ The [`Permalink`] and [`RelPermalink`] methods on a `Page` object return the fir
|
||||
[`Permalink`]: /methods/page/permalink
|
||||
[`RelPermalink`]: /methods/page/relpermalink
|
||||
|
||||
__from `single.json.json`:__
|
||||
From `single.json.json`:
|
||||
|
||||
```go-html-template
|
||||
{{ .RelPermalink }} → /that-page/
|
||||
{{ with .OutputFormats.Get "json" }}
|
||||
@@ -206,7 +208,7 @@ __from `single.json.json`:__
|
||||
|
||||
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.
|
||||
|
||||
**Same template file as above with json output format's `permalinkable` set to true:**
|
||||
This is the same template file as above with the `json` output format's `permalinkable` parameter set to `true`:
|
||||
|
||||
```go-html-template
|
||||
{{ .RelPermalink }} → /that-page/index.json
|
||||
@@ -215,34 +217,25 @@ In order for them to return the output format of the current template file inste
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
From content files, you can use the `ref` or `relref` shortcodes:
|
||||
## Template lookup order
|
||||
|
||||
```go-html-template
|
||||
[Neat]({{</* ref "blog/neat.md" "amp" */>}})
|
||||
[Who]({{</* relref "about.md#who" "amp" */>}})
|
||||
Each output format requires a template conforming to the [template lookup order].
|
||||
|
||||
For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name:
|
||||
|
||||
[template lookup order]: /templates/lookup-order/
|
||||
|
||||
```text
|
||||
[page kind].[output format].[suffix]
|
||||
```
|
||||
|
||||
## Templates for your output formats
|
||||
For example, for section pages:
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Hugo will look for the name given, so you can name it whatever you want. But if you want it treated as plain text, you should use the file suffix and, if needed, the name of the Output Format. The pattern is as follows:
|
||||
|
||||
```go-html-template
|
||||
[partial name].[OutputFormat].[suffix]
|
||||
```
|
||||
|
||||
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" . }}
|
||||
```
|
||||
Output format|Template path
|
||||
:--|:--
|
||||
`html`|`layouts/_default/section.html.html`
|
||||
`json`|`layouts/_default/section.json.json`
|
||||
`rss`|`layouts/_default/section.rss.xml`
|
||||
|
||||
[site configuration]: /getting-started/configuration/
|
||||
[lookup order]: /templates/lookup-order/
|
||||
[media type]: https://en.wikipedia.org/wiki/Media_type
|
||||
[`kind`]: /methods/page/kind/
|
||||
|
||||
Reference in New Issue
Block a user