mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-18 21:11:19 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '77b976dd92b4f66657d83d875aef0c617df492d9'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-08-30 19:24:34 +02:00
parent e847a98db6 77b976dd92
commit db45dbbee8
302 changed files with 1289 additions and 19021 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/content/en/templates/_index.md
View File

@@ -12,3 +12,5 @@ categories: [templates]
keywords: []
aliases: [/templates/overview/,/templates/content]
---
A template is an HTML file with [template actions](/getting-started/glossary/#template-action), located within the layouts directory of a project, theme, or module. Visit the topics below, in the order presented, to understand template selection and creation.

2
docs/content/en/templates/data-templates.md
View File

@@ -261,7 +261,7 @@ If you change any local file and the LiveReload is triggered, Hugo will read the
[markdownify]: /functions/markdownify/
[OAuth]: https://en.wikipedia.org/wiki/OAuth
[partials]: /templates/partials/
[toml]: https://github.com/toml-lang/toml
[toml]: https://toml.io/en/latest
[variadic]: https://en.wikipedia.org/wiki/Variadic_function
[vars]: /variables/
[yaml]: https://yaml.org/spec/

348
docs/content/en/templates/lists/index.md
View File

@@ -88,23 +88,23 @@ You can now access this `_index.md`'s' content in your list template:
{{< code file="layouts/_default/list.html" >}}
{{ define "main" }}
<main>
<article>
<header>
<h1>{{ .Title }}</h1>
</header>
<!-- "{{ .Content }}" pulls from the markdown content of the corresponding _index.md -->
{{ .Content }}
</article>
<ul>
<!-- Ranges through content/posts/*.md -->
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Date.Format "2006-01-02" }} | {{ .Title }}</a>
</li>
{{ end }}
</ul>
</main>
<main>
<article>
<header>
<h1>{{ .Title }}</h1>
</header>
<!-- "{{ .Content }}" pulls from the markdown content of the corresponding _index.md -->
{{ .Content }}
</article>
<ul>
<!-- Ranges through content/posts/*.md -->
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Date.Format "2006-01-02" }} | {{ .Title }}</a>
</li>
{{ end }}
</ul>
</main>
{{ end }}
{{< /code >}}
@@ -113,17 +113,17 @@ This above will output the following HTML:
{{< code file="example.com/posts/index.html" copy=false >}}
<!--top of your baseof code-->
<main>
<article>
<header>
<h1>My Go Journey</h1>
</header>
<p>I decided to start learning Go in March 2017.</p>
<p>Follow my journey through this new blog.</p>
</article>
<ul>
<li><a href="/posts/post-01/">Post 1</a></li>
<li><a href="/posts/post-02/">Post 2</a></li>
</ul>
<article>
<header>
<h1>My Go Journey</h1>
</header>
<p>I decided to start learning Go in March 2017.</p>
<p>Follow my journey through this new blog.</p>
</article>
<ul>
<li><a href="/posts/post-01/">Post 1</a></li>
<li><a href="/posts/post-02/">Post 2</a></li>
</ul>
</main>
<!--bottom of your baseof-->
{{< /code >}}
@@ -137,16 +137,16 @@ Using this same `layouts/_default/list.html` template and applying it to the `qu
{{< code file="example.com/quote/index.html" copy=false >}}
<!--baseof-->
<main>
<article>
<header>
<!-- Hugo assumes that .Title is the name of the section since there is no _index.md content file from which to pull a "title:" field -->
<h1>Quotes</h1>
</header>
</article>
<ul>
<li><a href="https://example.com/quote/quotes-01/">Quote 1</a></li>
<li><a href="https://example.com/quote/quotes-02/">Quote 2</a></li>
</ul>
<article>
<header>
<!-- Hugo assumes that .Title is the name of the section since there is no _index.md content file from which to pull a "title:" field -->
<h1>Quotes</h1>
</header>
</article>
<ul>
<li><a href="https://example.com/quote/quotes-01/">Quote 1</a></li>
<li><a href="https://example.com/quote/quotes-02/">Quote 2</a></li>
</ul>
</main>
<!--baseof-->
{{< /code >}}
@@ -202,12 +202,12 @@ Hugo lists render the content based on metadata you provide in [front matter]. I
{{< code file="layouts/partials/default-order.html" >}}
<ul>
{{ range .Pages }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
{{ range .Pages }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
</ul>
{{< /code >}}
@@ -217,12 +217,12 @@ Lower weight gets higher precedence. So content with lower weight will come firs
{{< code file="layouts/partials/by-weight.html" >}}
<ul>
{{ range .Pages.ByWeight }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
{{ range .Pages.ByWeight }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
</ul>
{{< /code >}}
@@ -230,13 +230,13 @@ Lower weight gets higher precedence. So content with lower weight will come firs
{{< code file="layouts/partials/by-date.html" >}}
<ul>
<!-- orders content according to the "date" field in front matter -->
{{ range .Pages.ByDate }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
<!-- orders content according to the "date" field in front matter -->
{{ range .Pages.ByDate }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
</ul>
{{< /code >}}
@@ -244,13 +244,13 @@ Lower weight gets higher precedence. So content with lower weight will come firs
{{< code file="layouts/partials/by-publish-date.html" >}}
<ul>
<!-- orders content according to the "publishdate" field in front matter -->
{{ range .Pages.ByPublishDate }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
<!-- orders content according to the "publishdate" field in front matter -->
{{ range .Pages.ByPublishDate }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
</ul>
{{< /code >}}
@@ -258,12 +258,12 @@ Lower weight gets higher precedence. So content with lower weight will come firs
{{< code file="layouts/partials/by-expiry-date.html" >}}
<ul>
{{ range .Pages.ByExpiryDate }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
{{ range .Pages.ByExpiryDate }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
</ul>
{{< /code >}}
@@ -271,13 +271,13 @@ Lower weight gets higher precedence. So content with lower weight will come firs
{{< code file="layouts/partials/by-last-mod.html" >}}
<ul>
<!-- orders content according to the "lastmod" field in front matter -->
{{ range .Pages.ByLastmod }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
<!-- orders content according to the "lastmod" field in front matter -->
{{ range .Pages.ByLastmod }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
</ul>
{{< /code >}}
@@ -285,13 +285,13 @@ Lower weight gets higher precedence. So content with lower weight will come firs
{{< code file="layouts/partials/by-length.html" >}}
<ul>
<!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) -->
{{ range .Pages.ByLength }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
<!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) -->
{{ range .Pages.ByLength }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
</ul>
{{< /code >}}
@@ -299,13 +299,13 @@ Lower weight gets higher precedence. So content with lower weight will come firs
{{< code file="layouts/partials/by-title.html" >}}
<ul>
<!-- ranges through content in ascending order according to the "title" field set in front matter -->
{{ range .Pages.ByTitle }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
<!-- ranges through content in ascending order according to the "title" field set in front matter -->
{{ range .Pages.ByTitle }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
</ul>
{{< /code >}}
@@ -313,13 +313,13 @@ Lower weight gets higher precedence. So content with lower weight will come firs
{{< code file="layouts/partials/by-link-title.html" >}}
<ul>
<!-- ranges through content in ascending order according to the "linktitle" field in front matter. If a "linktitle" field is not set, the range will start with content that only has a "title" field and use that value for .LinkTitle -->
{{ range .Pages.ByLinkTitle }}
<li>
<h1><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
<!-- ranges through content in ascending order according to the "linktitle" field in front matter. If a "linktitle" field is not set, the range will start with content that only has a "title" field and use that value for .LinkTitle -->
{{ range .Pages.ByLinkTitle }}
<li>
<h1><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
</ul>
{{< /code >}}
@@ -348,12 +348,12 @@ Reversing order can be applied to any of the above methods. The following uses `
{{< code file="layouts/partials/by-date-reverse.html" >}}
<ul>
{{ range .Pages.ByDate.Reverse }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
{{ range .Pages.ByDate.Reverse }}
<li>
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
<time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
</li>
{{ end }}
</ul>
{{< /code >}}
@@ -366,15 +366,15 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
{{< code file="layouts/partials/by-page-field.html" >}}
<!-- Groups content according to content section. The ".Key" in this instance will be the section's title. -->
{{ range .Pages.GroupBy "Section" }}
<h3>{{ .Key }}</h3>
<ul>
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
</ul>
{{ end }}
{{< /code >}}
@@ -383,21 +383,21 @@ In the above example, you may want `{{ .Title }}` to point the `title` field you
{{< code file="layouts/partials/by-page-field.html" >}}
<!-- Groups content according to content section.-->
{{ range .Pages.GroupBy "Section" }}
<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter -->
{{ with $.Site.GetPage "section" .Key }}
<h3>{{ .Title }}</h3>
{{ else }}
<!-- If no _index.md is available, ".Key" defaults to the section title and filters to title casing -->
<h3>{{ .Key | title }}</h3>
{{ end }}
<ul>
<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter -->
{{ with $.Site.GetPage "section" .Key }}
<h3>{{ .Title }}</h3>
{{ else }}
<!-- If no _index.md is available, ".Key" defaults to the section title and filters to title casing -->
<h3>{{ .Key | title }}</h3>
{{ end }}
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
</ul>
{{ end }}
{{< /code >}}
@@ -406,15 +406,15 @@ In the above example, you may want `{{ .Title }}` to point the `title` field you
{{< code file="layouts/partials/by-page-date.html" >}}
<!-- Groups content by month according to the "date" field in front matter -->
{{ range .Pages.GroupByDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
</ul>
{{ end }}
{{< /code >}}
@@ -425,15 +425,15 @@ In the above example, you may want `{{ .Title }}` to point the `title` field you
{{< code file="layouts/partials/by-page-publish-date.html" >}}
<!-- Groups content by month according to the "publishDate" field in front matter -->
{{ range .Pages.GroupByPublishDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
</ul>
{{ end }}
{{< /code >}}
@@ -445,15 +445,15 @@ In the above example, you may want `{{ .Title }}` to point the `title` field you
{{< code file="layouts/partials/by-page-expiry-date.html" >}}
<!-- Groups content by month according to the "expiryDate" field in front matter -->
{{ range .Pages.GroupByExpiryDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
</ul>
{{ end }}
{{< /code >}}
@@ -464,15 +464,15 @@ In the above example, you may want `{{ .Title }}` to point the `title` field you
{{< code file="layouts/partials/by-page-lastmod.html" >}}
<!-- Groups content by month according to the "lastMod" field in front matter -->
{{ range .Pages.GroupByLastmod "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Lastmod.Format "Mon, Jan 2, 2006" }}</div>
</li>
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Lastmod.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
</ul>
{{ end }}
{{< /code >}}
@@ -483,16 +483,16 @@ In the above example, you may want `{{ .Title }}` to point the `title` field you
{{< code file="layouts/partials/by-page-param.html" >}}
<!-- Groups content according to the "param_key" field in front matter -->
{{ range .Pages.GroupByParam "param_key" }}
<h3>{{ .Key }}</h3>
<ul>
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
</ul>
{{ end }}
{{< /code >}}
### By page parameter in date format
@@ -502,15 +502,15 @@ The following template takes grouping by `date` a step further and uses Go's lay
{{< code file="layouts/partials/by-page-param-as-date.html" >}}
<!-- Groups content by month according to the "param_key" field in front matter -->
{{ range .Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
</ul>
{{ end }}
{{< /code >}}
@@ -552,15 +552,15 @@ Here is the ordering for the example that follows:
{{< code file="layouts/partials/by-group-by-page.html" >}}
{{ range .Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3>
<ul>
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages.ByTitle }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
</ul>
{{ end }}
{{< /code >}}

24
docs/content/en/templates/lookup-order.md
View File

@@ -39,22 +39,38 @@ Section
Templates can live in either the project's or the themes' layout folders, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.
{{% /note %}}
## Regular pages
{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
## Home page
{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
## Single pages
{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
## Section pages
A section page is a list of pages within a given section.
{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
## Taxonomy pages
A taxonomy page is a list of terms within a given taxonomy. The examples below assume the following site configuration:
{{< code-toggle file=hugo copy=false >}}
[taxonomies]
category = 'categories'
{{< /code-toggle >}}
{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
## Term pages
A term page is a list of pages associated with a given term. The examples below assume the following site configuration:
{{< code-toggle file=hugo copy=false >}}
[taxonomies]
category = 'categories'
{{< /code-toggle >}}
{{< datatable-filtered "output" "layouts" "Kind == term" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}

67
docs/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
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.
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.
@@ -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" . }}

26
docs/content/en/templates/partials.md
View File

@@ -128,29 +128,11 @@ Value: {{ partial "my-inline-partial.html" . }}
## Cached partials
The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows:
The `partialCached` template function provides significant performance gains for complex templates that don't need to be re-rendered on every invocation. See [details][partialcached].
```go-html-template
{{ partialCached "footer.html" . }}
```
## Examples
You can also pass additional parameters to `partialCached` to create *variants* of the cached partial.
For example, you can tell Hugo to only render the partial `footer.html` once per section:
```go-html-template
{{ partialCached "footer.html" . .Section }}
```
If you need to pass additional parameters to create unique variants, you can pass as many variant parameters as you need:
```go-html-template
{{ partialCached "footer.html" . .Params.country .Params.province }}
```
Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key.
### Example `header.html`
### `header.html`
The following `header.html` partial template is used for [spf13.com](https://spf13.com/):
@@ -175,7 +157,7 @@ The following `header.html` partial template is used for [spf13.com](https://spf
The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility.
{{% /note %}}
### Example `footer.html`
### `footer.html`
The following `footer.html` partial template is used for [spf13.com](https://spf13.com/):

7
docs/content/en/templates/sitemap-template.md
View File

@@ -27,12 +27,7 @@ With a multilingual project, Hugo generates:
Set the default values for [change frequency] and [priority], and the name of the generated file, in your site configuration.
{{< code-toggle file="hugo" >}}
[sitemap]
changefreq = 'monthly'
filename = 'sitemap.xml'
priority = 0.5
{{</ code-toggle >}}
{{< code-toggle config="sitemap" />}}
changefreq
: How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is `""` (change frequency omitted from rendered sitemap).

20
docs/content/en/templates/taxonomy-templates.md
View File

@@ -41,14 +41,16 @@ See [Template Lookup](/templates/lookup-order/).
A Taxonomy is a `map[string]WeightedPages`.
.Get(term)
: Returns the WeightedPages for a term.
.Get TERM
: Returns the WeightedPages for a given term. For example: ;
`site.Taxonomies.tags.Get "tag-a"`.
.Count(term)
: The number of pieces of content assigned to this term.
.Count TERM
: The number of pieces of content assigned to the given term. For example: \
`site.Taxonomies.tags.Count "tag-a"`.
.Alphabetical
: Returns an OrderedTaxonomy (slice) ordered by Term.
: Returns an OrderedTaxonomy (slice) ordered by term.
.ByCount
: Returns an OrderedTaxonomy (slice) ordered by number of entries.
@@ -78,6 +80,9 @@ Each element of the slice has:
.Count
: The number of pieces of content assigned to this term.
.Page
: Returns a page reference for this term.
.Pages
: All Pages assigned to this term. All [list methods][renderlists] are available to this.
@@ -89,9 +94,12 @@ WeightedPages is simply a slice of WeightedPage.
type WeightedPages []WeightedPage
```
.Count(term)
.Count
: The number of pieces of content assigned to this term.
.Page
: Returns a page reference for this term.
.Pages
: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists].