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

Merge commit 'a6e635ca7d905d9ec3ffd708db2694f680b03aae'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2024-08-09 15:17:43 +02:00
parent dbff48e6c3 a6e635ca7d
commit e99eba39e7
143 changed files with 3258 additions and 2109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/content/en/templates/404.md
View File

@@ -1,14 +1,14 @@
---
title: Custom 404 page
linkTitle: 404 template
linkTitle: 404 templates
description: Create a template to render a 404 error page.
categories: [templates]
keywords: ['404',page not found]
keywords: []
menu:
docs:
parent: templates
weight: 220
weight: 220
weight: 160
weight: 160
---
To render a 404 error page in the root of your site, create a 404 template in the root of the layouts directory. For example:
@@ -43,7 +43,7 @@ Amazon S3|See [details](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Cu
Apache|See [details](https://httpd.apache.org/docs/2.4/custom-error.html).
Azure Static Web Apps|See [details](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides).
Azure Storage|See [details](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website#setting-up-a-static-website).
Caddy|See [deatils](https://caddyserver.com/docs/caddyfile/directives/handle_errors).
Caddy|See [details](https://caddyserver.com/docs/caddyfile/directives/handle_errors).
Cloudflare Pages|See [details](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior).
DigitalOcean App Platform|See [details](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
Firebase|See [details](https://firebase.google.com/docs/hosting/full-config#404).

13
docs/content/en/templates/_common/_index.md Normal file
View File

@@ -0,0 +1,13 @@
---
cascade:
_build:
list: never
publishResources: false
render: never
---
<!--
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->

9
docs/content/en/templates/_common/filter-sort-group.md Normal file
View File

@@ -0,0 +1,9 @@
---
# Do not remove front matter.
---
{{% note %}}
The [page collections quick reference guide] describes methods and functions to filter, sort, and group page collections.
[page collections quick reference guide]: /quick-reference/page-collections/
{{% /note %}}

19
docs/content/en/templates/base.md
View File

@@ -1,13 +1,13 @@
---
title: Base templates and blocks
description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page).
title: Base templates
description: The base and block construct allows you to define the outer shell of your master templates (i.e., the chrome of the page).
categories: [templates,fundamentals]
keywords: [blocks,base]
keywords: []
menu:
docs:
parent: templates
weight: 40
weight: 40
weight: 50
weight: 50
toc: true
aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
---
@@ -50,7 +50,7 @@ The following defines a simple base template at `_default/baseof.html`. As a def
## Override the base template
From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
{{< code file=layouts/_default/list.html >}}
{{ define "main" }}
@@ -78,7 +78,7 @@ Code that you put outside the block definitions *can* break your layout. This ev
[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6)
{{% /note %}}
The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]:
The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your default [single template]:
{{< code file=layouts/_default/single.html >}}
{{ define "title" }}
@@ -91,7 +91,4 @@ The following shows how you can override both the `"main"` and `"title"` block a
{{ end }}
{{< /code >}}
[hugolists]: /templates/lists/
[lookup]: /templates/lookup-order/
[rendering the section]: /templates/section-templates/
[singletemplate]: /templates/single-page-templates/
[single template]: /templates/types/#single

44
docs/content/en/templates/views.md → docs/content/en/templates/content-view.md
View File

@@ -2,25 +2,24 @@
title: Content view templates
description: Hugo can render alternative views of your content, useful in list and summary views.
categories: [templates]
keywords: [views]
keywords: []
menu:
docs:
parent: templates
weight: 110
weight: 110
weight: 120
weight: 120
toc: true
aliases: [/templates/views/]
---
These alternative **content views** are especially useful in [list templates][lists].
The following are common use cases for content views:
* You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself.
* You want content of every type to be shown on the home page but only with limited [summary views][summaries].
* You only want a bulleted list of your content in a [taxonomy template]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself.
## Create a content view
To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single template], `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
```txt
▾ layouts/
@@ -31,32 +30,22 @@ To create a new view, create a template in each of your different content type d
▾ project/
li.html
single.html
summary.html
```
Hugo also has support for a default content view template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
```txt
▾ layouts/
▾ _default/
li.html
single.html
summary.html
```
## Which template will be rendered?
The following is the [lookup order] for content views:
The following is the lookup order for content views ordered by specificity.
1. `/layouts/<TYPE>/<VIEW>.html`
2. `/layouts/_default/<VIEW>.html`
3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
4. `/themes/<THEME>/layouts/_default/<VIEW>.html`
1. `/layouts/<SECTION>/<VIEW>.html`
1. `/layouts/_default/<VIEW>.html`
1. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
1. `/themes/<THEME>/layouts/<SECTION>/<VIEW>.html`
1. `/themes/<THEME>/layouts/_default/<VIEW>.html`
## Example: content view inside a list
The following example demonstrates how to use content views inside your [list templates][lists].
### `list.html`
In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
@@ -74,7 +63,7 @@ In this example, `.Render` is passed into the template to call the [render funct
### `summary.html`
Hugo passes the page object to the following `summary.html` view template.
Hugo passes the `Page` object to the following `summary.html` view template.
{{< code file=layouts/_default/summary.html >}}
<article class="post">
@@ -100,8 +89,7 @@ Continuing on the previous example, we can change our render function to use a s
</li>
{{< /code >}}
[lists]: /templates/lists/
[render]: /methods/page/render/
[single]: /templates/single-page-templates/
[single template]: /templates/types/#single
[summaries]: /content-management/summaries/
[taxonomylists]: /templates/taxonomy-templates/
[taxonomy template]: /templates/types/#taxonomy

6
docs/content/en/templates/embedded.md
View File

@@ -2,12 +2,12 @@
title: Embedded templates
description: Hugo provides embedded templates for common use cases.
categories: [templates]
keywords: [internal, analytics,]
keywords: []
menu:
docs:
parent: templates
weight: 190
weight: 190
weight: 200
weight: 200
toc: true
aliases: [/templates/internal]
---

55
docs/content/en/templates/home.md Normal file
View File

@@ -0,0 +1,55 @@
---
title: Home templates
description: The home page of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site's home page as a unique template.
categories: [templates]
keywords: []
menu:
docs:
parent: templates
weight: 60
weight: 60
toc: true
aliases: [/layout/homepage/,/templates/homepage-template/,/templates/homepage/]
---
The home template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website.
{{< youtube ut1xtRZ1QOA >}}
## Home template lookup order
See [Template Lookup](/templates/lookup-order/).
## Add content and front matter to the home page
The home page accepts content and front matter from an `_index.md` file. This file should live at the root of your `content` folder (i.e., `content/_index.md`). You can then add body copy and metadata to your home page the way you would any other content file.
See the home template below or [Content Organization][contentorg] for more information on the role of `_index.md` in adding content and front matter to list pages.
## Example home template
{{< code file=layouts/_default/home.html >}}
{{ define "main" }}
<main aria-role="main">
<header class="home-page-header">
<h1>{{ .Title }}</h1>
{{ with .Params.subtitle }}
<span class="subtitle">{{ . }}</span>
{{ end }}
</header>
<div class="home-page-content">
<!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
{{ .Content }}
</div>
<div>
{{ range first 10 .Site.RegularPages }}
{{ .Render "summary" }}
{{ end }}
</div>
</main>
{{ end }}
{{< /code >}}
[contentorg]: /content-management/organization/
[lookup]: /templates/lookup-order/

56
docs/content/en/templates/homepage.md
View File

@@ -1,56 +0,0 @@
---
title: Homepage template
description: The homepage of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site's homepage as a unique template.
categories: [templates]
keywords: [homepage]
menu:
docs:
parent: templates
weight: 70
weight: 70
toc: true
aliases: [/layout/homepage/,/templates/homepage-template/]
---
The homepage template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website.
{{< youtube ut1xtRZ1QOA >}}
## Homepage template lookup order
See [Template Lookup](/templates/lookup-order/).
## Add content and front matter to the homepage
The homepage, similar to other [list pages in Hugo][lists], accepts content and front matter from an `_index.md` file. This file should live at the root of your `content` folder (i.e., `content/_index.md`). You can then add body copy and metadata to your homepage the way you would any other content file.
See the homepage template below or [Content Organization][contentorg] for more information on the role of `_index.md` in adding content and front matter to list pages.
## Example homepage template
{{< code file=layouts/index.html >}}
{{ define "main" }}
<main aria-role="main">
<header class="homepage-header">
<h1>{{ .Title }}</h1>
{{ with .Params.subtitle }}
<span class="subtitle">{{ . }}</span>
{{ end }}
</header>
<div class="homepage-content">
<!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
{{ .Content }}
</div>
<div>
{{ range first 10 .Site.RegularPages }}
{{ .Render "summary" }}
{{ end }}
</div>
</main>
{{ end }}
{{< /code >}}
[contentorg]: /content-management/organization/
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/

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

@@ -403,7 +403,7 @@ Use the [`template`] function to include one or more of Hugo's [embedded templat
Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:
[partial templates]: /templates/partials
[partial templates]: /templates/partial
```go-html-template
{{ partial "breadcrumbs.html" . }}

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

@@ -1,240 +0,0 @@
---
title: Lists of content in Hugo
linkTitle: List templates
description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list.
categories: [templates]
keywords: [lists,sections,rss,taxonomies,terms]
menu:
docs:
parent: templates
weight: 60
weight: 60
toc: true
aliases: [/templates/list/,/layout/indexes/]
---
## What is a list page template?
{{< youtube 8b2YTSMdMps >}}
A list page template is a template used to render multiple pieces of content in a single HTML page. The exception to this rule is the homepage, which is still a list but has its own [dedicated template][homepage].
Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is traditionally listed:
* [Home page](/templates/homepage)
* [Section pages](/templates/section-templates)
* [Taxonomy pages](/templates/taxonomy-templates)
* [Taxonomy term pages](/templates/taxonomy-templates)
* [RSS feeds](/templates/rss)
* [Sitemaps](/templates/sitemap-template)
For template lookup order, see [Template Lookup](/templates/lookup-order/).
The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually:
[![Image demonstrating a hierarchical website sitemap.](site-hierarchy.svg)](site-hierarchy.svg)
## Add content and front matter to list pages
Add content and front matter to list pages by creating an _index.md file for `home`, `section`, `taxonomy`, and `term` pages.
The following is an example of a typical Hugo project directory's content:
```txt
.
...
├── content
| ├── posts
| | ├── _index.md
| | ├── post-01.md
| | └── post-02.md
| └── quote
| | ├── quote-01.md
| | └── quote-02.md
...
```
Using the above example, let's assume you have the following in `content/posts/_index.md`:
{{< code file=content/posts/_index.md >}}
---
title: My Go Journey
date: 2017-03-23
publishdate: 2017-03-24
---
I decided to start learning Go in March 2017.
Follow my journey through this new blog.
{{< /code >}}
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="{{ .RelPermalink }}">{{ .Date.Format "2006-01-02" }} | {{ .LinkTitle }}</a>
</li>
{{ end }}
</ul>
</main>
{{ end }}
{{< /code >}}
This above will output the following HTML:
{{< code file=example.com/posts/index.html >}}
<!--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>
</main>
<!--bottom of your baseof-->
{{< /code >}}
### List pages without `_index.md`
You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a list template, the page will be created but with no `{{ .Content }}` and only the default values for `.Title` etc.
Using this same `layouts/_default/list.html` template and applying it to the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from:
{{< code file=example.com/quote/index.html >}}
<!--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.org/quote/quotes-01/">Quote 1</a></li>
<li><a href="https://example.org/quote/quotes-02/">Quote 2</a></li>
</ul>
</main>
<!--baseof-->
{{< /code >}}
{{% note %}}
By default, Hugo capitalizes and pluralizes automatic list titles including section, taxonomy, and term pages. You can disable these transformations by setting [`capitalizeListTitles`] and [`pluralizeListTitles`] in your site configuration.
You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. See [details].
[`capitalizeListTitles`]: /getting-started/configuration/#capitalizelisttitles
[`pluralizeListTitles`]: /getting-started/configuration/#pluralizelisttitles
[details]: /getting-started/configuration/#configure-title-case
{{% /note %}}
## Example list templates
### Section template
This list template has been modified slightly from a template originally used in [spf13.com](https://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base]. The examples that follow also use the [content view templates][views] `li.html` or `summary.html`.
{{< code file=layouts/section/posts.html >}}
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
<main>
<div>
<h1>{{ .Title }}</h1>
<ul>
<!-- Renders the li.html content view for each content/posts/*.md -->
{{ range .Pages }}
{{ .Render "li" }}
{{ end }}
</ul>
</div>
</main>
{{ partial "footer.html" . }}
{{< /code >}}
### Taxonomy template
{{< code file=layouts/_default/taxonomy.html >}}
{{ define "main" }}
<main>
<div>
<h1>{{ .Title }}</h1>
<!-- ranges through each of the content files associated with a particular taxonomy term and renders the summary.html content view -->
{{ range .Pages }}
{{ .Render "summary" }}
{{ end }}
</div>
</main>
{{ end }}
{{< /code >}}
## Sort content
By default, Hugo sorts page collections by:
1. Page [weight]
2. Page [date] (descending)
3. Page [linkTitle], falling back to page [title]
4. Page file path if the page is backed by a file
[date]: /methods/page/date/
[weight]: /methods/page/weight/
[linkTitle]: /methods/page/linktitle/
[title]: /methods/page/title/
Change the sort order using any of the methods below.
{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. omitElementIDs=true >}}
## Group content
Group your content by field, parameter, or date using any of the methods below.
{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. omitElementIDs=true >}}
## Filtering and limiting lists
Sometimes you only want to list a subset of the available content. A
common is to only display posts from [main sections]
on the blog's homepage.
See the documentation on [`where`] and
[`first`] for further details.
[base]: /templates/base/
[bepsays]: https://bepsays.com/en/2016/12/19/hugo-018/
[directorystructure]: /getting-started/directory-structure/
[`Format` function]: /methods/time/format/
[front matter]: /content-management/front-matter/
[getpage]: /methods/page/getpage/
[homepage]: /templates/homepage/
[mentalmodel]: https://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
[partials]: /templates/partials/
[RSS 2.0]: https://cyber.harvard.edu/rss/rss.html
[rss]: /templates/rss/
[sections]: /content-management/sections/
[sectiontemps]: /templates/section-templates/
[taxlists]: /templates/taxonomy-templates/#taxonomy-templates
[taxterms]: /templates/taxonomy-templates/#term-templates
[taxvars]: /methods/taxonomy/
[views]: /templates/views/
[`where`]: /functions/collections/where/
[`first`]: /functions/collections/first/
[main sections]: /methods/site/mainsections/
[`time.Format`]: /functions/time/format/

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

@@ -1,13 +1,14 @@
---
title: Template lookup order
linkTitle: Lookup order
description: Hugo uses the rules below to select a template for a given page, starting from the most specific.
categories: [templates,fundamentals]
keywords: [templates]
keywords: []
menu:
docs:
parent: templates
weight: 30
weight: 30
weight: 40
weight: 40
toc: true
---
@@ -99,23 +100,29 @@ layouts/
└── single.html <-- renders about.md
```
## Home page
## Home templates
These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
## Single pages
## Single templates
These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
## Section pages
## Section templates
A section page is a list of pages within a given section.
These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
## Taxonomy pages
## Taxonomy templates
A taxonomy page is a list of terms within a given taxonomy. The examples below assume the following site configuration:
These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
The examples below assume the following site configuration:
{{< code-toggle file=hugo >}}
[taxonomies]
@@ -124,9 +131,11 @@ category = 'categories'
{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
## Term pages
## Term templates
A term page is a list of pages associated with a given term. The examples below assume the following site configuration:
These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
The examples below assume the following site configuration:
{{< code-toggle file=hugo >}}
[taxonomies]
@@ -134,3 +143,16 @@ category = 'categories'
{{< /code-toggle >}}
{{< datatable-filtered "output" "layouts" "Kind == term" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
## RSS templates
These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
The examples below assume the following site configuration:
{{< code-toggle file=hugo >}}
[taxonomies]
category = 'categories'
{{< /code-toggle >}}
{{< datatable-filtered "output" "layouts" "OutputFormat == rss" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}

11
docs/content/en/templates/menu-templates.md → docs/content/en/templates/menu.md
View File

@@ -1,15 +1,16 @@
---
title: Menu templates
title: Menus
description: Create templates to render one or more menus.
categories: [templates]
keywords: [lists,sections,menus]
keywords: []
menu:
docs:
identifier: templates-menu
parent: templates
weight: 140
weight: 140
weight: 180
weight: 180
toc: true
aliases: [/templates/menus/]
aliases: [/templates/menus/,/templates/menu-templates/]
---
## Overview

8
docs/content/en/templates/output-formats.md
View File

@@ -2,7 +2,7 @@
title: Custom output formats
description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format.
categories: [templates,fundamentals]
keywords: ["amp", "outputs", "rss"]
keywords: []
menu:
docs:
parent: templates
@@ -79,7 +79,7 @@ isPlainText = true
protocol = "bep://"
{{</ code-toggle >}}
The above example is fictional, but if used for the homepage on a site with `baseURL` `https://example.org`, it will produce a plain text homepage with the URL `bep://example.org/myindex.enr`.
The above example is fictional, but if used for the home page on a site with `baseURL` `https://example.org`, it will produce a plain text home page with the URL `bep://example.org/myindex.enr`.
### Configure output formats
@@ -163,7 +163,7 @@ Example from site configuration file:
Note that in the above examples, the _output formats_ for `section`,
`taxonomy` and `term` will stay at their default value `['html','rss']`.
* The `outputs` definition is per page [`Kind`][page_kinds].
* 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`:
@@ -242,9 +242,7 @@ The partial below is a plain text template . The output format is `csv`, and sin
{{ partial "mytextpartial.csv" . }}
```
[base]: /templates/base/
[site configuration]: /getting-started/configuration/
[lookup order]: /templates/lookup-order/
[media type]: https://en.wikipedia.org/wiki/Media_type
[partials]: /templates/partials/
[`kind`]: /methods/page/kind/

354
docs/content/en/templates/pagination.md
View File

@@ -1,161 +1,293 @@
---
title: Pagination
description: Hugo supports pagination for your homepage, section pages, and taxonomies.
description: Split a list page into two or more subsets.
categories: [templates]
keywords: [lists,sections,pagination]
keywords: []
menu:
docs:
parent: templates
weight: 100
weight: 100
weight: 190
weight: 190
toc: true
aliases: [/extras/pagination,/doc/pagination/]
---
The real power of Hugo pagination shines when combined with the [`where`] function and its SQL-like operators: [`first`], [`last`], and [`after`]. You can even [order the content][lists] the way you've become used to with Hugo.
Displaying a large page collection on a list page is not user-friendly:
## Configure pagination
- A massive list can be intimidating and difficult to navigate. Users may get lost in the sheer volume of information.
- Large pages take longer to load, which can frustrate users and lead to them abandoning the site.
- Without any filtering or organization, finding a specific item becomes a tedious scrolling exercise.
Pagination can be configured in your [site configuration][configuration]:
paginate
: default = `10`. This setting can be overridden within the template.
paginatePath
: default = `page`. Allows you to set a different path for your pagination pages.
Setting `paginate` to a positive value will split the list pages for the homepage, sections and taxonomies into chunks of that size. But note that the generation of the pagination pages for sections, taxonomies and homepage is *lazy* --- the pages will not be created if not referenced by a `.Paginator` (see below).
`paginatePath` is used to adapt the `URL` to the pages in the paginator (the default setting will produce URLs on the form `/page/1/`.
## List paginator pages
Improve usability by paginating `home`, `section`, `taxonomy`, and `term` pages.
{{% note %}}
Paginate a page collection in list templates for these page kinds: `home`, `section`, `taxonomy`, or `term`. You cannot paginate a page collection in a template for the `page` page kind.
The most common templating mistake related to pagination is invoking pagination more than once for a given list page. See the [caching](#caching) section below.
{{% /note %}}
There are two ways to configure and use a `.Paginator`:
## Terminology
1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page*.
2. Select another set of pages with the available template functions and ordering options, and pass the slice to `.Paginate`, e.g.
* `{{ range (.Paginate ( first 50 .Pages.ByTitle )).Pages }}` or
* `{{ range (.Paginate .RegularPagesRecursive).Pages }}`.
paginate
: To split a [list page] into two or more subsets.
For a given **Page**, it's one of the options above. The `.Paginator` is static and cannot change once created.
pagination
: The process of paginating a list page.
If you call `.Paginator` or `.Paginate` multiple times on the same page, you should ensure all the calls are identical. Once *either* `.Paginator` or `.Paginate` is called while generating a page, its result is cached, and any subsequent similar call will reuse the cached result. This means that any such calls which do not match the first one will not behave as written.
pager
: Created during pagination, a pager contains a subset of a list page and navigation links to other pagers.
(Remember that function arguments are eagerly evaluated, so a call like `$paginator := cond x .Paginator (.Paginate .RegularPagesRecursive)` is an example of what you should *not* do. Use `if`/`else` instead to ensure exactly one evaluation.)
paginator
: A collection of pagers.
The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page:
[list page]: /getting-started/glossary/#list-page
* `{{ range (.Paginator 5).Pages }}`
* `{{ $paginator := .Paginate (where .Pages "Type" "posts") 5 }}`
## Configuration
It is also possible to use the `GroupBy` functions in combination with pagination:
Control pagination behavior in your site configuration. These are the default settings:
{{< code-toggle file=hugo config=pagination />}}
disableAliases
: (`bool`) Whether to disable alias generation for the first pager. Default is `false`.
pagerSize
: (`int`) The number of pages per pager. Default is `10`.
path
: (`string`) The segment of each pager URL indicating that the target page is a pager. Default is `page`.
With multilingual sites you can define the pagination behavior for each language:
{{< code-toggle file=hugo >}}
[languages.en]
contentDir = 'content/en'
languageCode = 'en-US'
languageDirection = 'ltr'
languageName = 'English'
weight = 1
[languages.en.pagination]
disableAliases = true
pagerSize = 10
path = 'page'
[languages.de]
contentDir = 'content/de'
languageCode = 'de-DE'
languageDirection = 'ltr'
languageName = 'Deutsch'
weight = 2
[languages.de.pagination]
disableAliases = true
pagerSize = 20
path = 'blatt'
{{< /code-toggle >}}
## Methods
To paginate a `home`, `section`, `taxonomy`, or `term` page, invoke either of these methods on the `Page` object in the corresponding template:
- [`Paginate`]
- [`Paginator`]
The `Paginate` method is more flexible, allowing you to:
- Paginate any page collection
- Filter, sort, and group the page collection
- Override the number of pages per pager as defined in your site configuration
By comparison, the `Paginator` method paginates the page collection passed into the template, and you cannot override the number of pages per pager.
[`Paginate`]: /methods/page/paginate/
[`Paginator`]: /methods/page/paginator/
## Examples
To paginate a list page using the `Paginate` method:
```go-html-template
{{ range (.Paginate (.Pages.GroupByDate "2006")).PageGroups }}
{{ $pages := where site.RegularPages "Type" "posts" }}
{{ $paginator := .Paginate $pages.ByTitle 7 }}
{{ range $paginator.Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ template "_internal/pagination.html" . }}
```
## Build the navigation
In the example above, we:
1. Build a page collection
2. Sort the page collection by title
3. Paginate the page collection, with 7 pages per pager
4. Range over the paginated page collection, rendering a link to each page
5. Call the embedded pagination template to create navigation links between pagers
To paginate a list page using the `Paginator` method:
```go-html-template
{{ range .Paginator.Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ template "_internal/pagination.html" . }}
```
In the example above, we:
1. Paginate the page collection passed into the template, with the default number of pages per pager
2. Range over the paginated page collection, rendering a link to each page
3. Call the embedded pagination template to create navigation links between pagers
## Caching
{{% note %}}
The most common templating mistake related to pagination is invoking pagination more than once for a given list page.
{{% /note %}}
Regardless of pagination method, the initial invocation is cached and cannot be changed. If you invoke pagination more than once for a given list page, subsequent invocations use the cached result. This means that subsequent invocations will not behave as written.
When paginating conditionally, do not use the `compare.Conditional` function due to its eager evaluation of arguments. Use an `if-else` construct instead.
[`compare.Conditional`]: /functions/compare/conditional/
## Grouping
Use pagination with any of the [grouping methods]. For example:
[grouping methods]: /quick-reference/page-collections/#group
```go-html-template
{{ $pages := where site.RegularPages "Type" "posts" }}
{{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }}
{{ range $paginator.PageGroups }}
<h2>{{ .Key }}</h2>
{{ range .Pages }}
<h3><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h3>
{{ end }}
{{ end }}
{{ template "_internal/pagination.html" . }}
```
[grouping methods]: /quick-reference/page-collections/#group
## Navigation
As shown in the examples above, the easiest way to add navigation between pagers is with Hugo's embedded pagination template:
```go-html-template
{{ template "_internal/pagination.html" . }}
```
The embedded pagination template has two formats: `default` and `terse`. The above is equivalent to:
```go-html-template
{{ template "_internal/pagination.html" (dict "page" . "format" "default") }}
```
The `terse` format has fewer controls and page slots, consuming less space when styled as a horizontal list. To use the `terse` format:
```go-html-template
{{ template "_internal/pagination.html" (dict "page" . "format" "terse") }}
```
{{% note %}}
To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
`{{ partial "pagination" . }}`
`{{ partial "pagination.html" . }}`
[`partial`]: /functions/partials/include/
[source code]: {{% eturl pagination %}}
{{% /note %}}
The easiest way to add this to your pages is to include the embedded template:
Create custom navigation components using any of the `Pager` methods:
```go-html-template
{{ template "_internal/pagination.html" . }}
{{< list-pages-in-section path=/methods/pager >}}
## Structure
The example below depicts the published site structure when paginating a list page.
With this content:
```text
content/
├── posts/
│ ├── _index.md
│ ├── post-1.md
│ ├── post-2.md
│ ├── post-3.md
│ └── post-4.md
└── _index.md
```
{{% note %}}
If you use any filters or ordering functions to create your `.Paginator` *and* you want the navigation buttons to be shown before the page listing, you must create the `.Paginator` before it's used.
{{% /note %}}
And this site configuration:
The following example shows how to create `.Paginator` before its used:
{{< code-toggle file=hugo >}}
[pagination]
disableAliases = false
pagerSize = 2
path = 'page'
{{< /code-toggle >}}
And this section template:
```go-html-template
{{ $paginator := .Paginate (where .Pages "Type" "posts") }}
{{ template "_internal/pagination.html" . }}
{{ range $paginator.Pages }}
{{ .Title }}
{{ range (.Paginate .Pages).Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
```
Without the `where` filter, the above example is even simpler:
```go-html-template
{{ template "_internal/pagination.html" . }}
{{ range .Paginator.Pages }}
{{ .Title }}
{{ end }}
```
If you want to build custom navigation, you can do so using the `.Paginator` object, which includes the following properties:
The published site has this structure:
PageNumber
: The current page's number in the pager sequence
URL
: The relative URL to the current pager
Pages
: The pages in the current pager
NumberOfElements
: The number of elements on this page
HasPrev
: Whether there are page(s) before the current
Prev
: The pager for the previous page
HasNext
: Whether there are page(s) after the current
Next
: The pager for the next page
First
: The pager for the first page
Last
: The pager for the last page
Pagers
: A list of pagers that can be used to build a pagination menu
PageSize
: Size of each pager
TotalPages
: The number of pages in the paginator
TotalNumberOfElements
: The number of elements on all pages in this paginator
## Additional information
The pages are built on the following form (`BLANK` means no value):
```txt
[SECTION/TAXONOMY/BLANK]/index.html
[SECTION/TAXONOMY/BLANK]/page/1/index.html => redirect to [SECTION/TAXONOMY/BLANK]/index.html
[SECTION/TAXONOMY/BLANK]/page/2/index.html
....
```text
public/
├── posts/
│ ├── page/
│ │ ├── 1/
│ │ │ └── index.html <-- alias to public/posts/index.html
│ │ └── 2/
│ │ └── index.html
│ ├── post-1/
│ │ └── index.html
│ ├── post-2/
│ │ └── index.html
│ ├── post-3/
│ │ └── index.html
│ ├── post-4/
│ │ └── index.html
│ └── index.html
└── index.html
```
[`first`]: /functions/collections/first/
[`last`]: /functions/collections/last/
[`after`]: /functions/collections/after/
[configuration]: /getting-started/configuration/
[lists]: /templates/lists/
[`where`]: /functions/collections/where/
To disable alias generation for the first pager, change your site configuration:
{{< code-toggle file=hugo >}}
[pagination]
disableAliases = true
pagerSize = 2
path = 'page'
{{< /code-toggle >}}
Now the published site will have this structure:
```text
public/
├── posts/
│ ├── page/
│ │ └── 2/
│ │ └── index.html
│ ├── post-1/
│ │ └── index.html
│ ├── post-2/
│ │ └── index.html
│ ├── post-3/
│ │ └── index.html
│ ├── post-4/
│ │ └── index.html
│ └── index.html
└── index.html
```

21
docs/content/en/templates/partials.md → docs/content/en/templates/partial.md
View File

@@ -2,27 +2,18 @@
title: Partial templates
description: Partials are smaller, context-aware components in your list and page templates that can be used economically to keep your templating DRY.
categories: [templates]
keywords: [lists,sections,partials]
keywords: []
menu:
docs:
parent: templates
weight: 120
weight: 120
weight: 110
weight: 110
toc: true
aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/]
aliases: [/templates/partials/,/layout/chrome/]
---
{{< youtube pjS4pOLyB7c >}}
## Partial template lookup order
Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order]. However, partials are simpler in that Hugo will only check in two places:
1. `layouts/partials/<PARTIALNAME>.html`
2. `themes/<THEME>/layouts/partials/<PARTIALNAME>.html`
This allows a theme's end user to copy a partial's contents into a file of the same name for [further customization][customize].
## Use partials in your templates
All partials for your Hugo project are located in a single `layouts/partials` directory. For better organization, you can create multiple subdirectories within `partials` as well:
@@ -50,7 +41,7 @@ All partials are called within your templates using the following pattern:
```
{{% note %}}
One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/).
One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/#context).
{{% /note %}}
{{% note %}}
@@ -175,8 +166,6 @@ The following `footer.html` partial template is used for [spf13.com](https://spf
[context]: /templates/introduction/
[customize]: /hugo-modules/theme-components/
[listtemps]: /templates/lists/
[lookup order]: /templates/lookup-order/
[partialcached]: /functions/partials/includecached/
[singletemps]: /templates/single-page-templates/
[themes]: /themes/

10
docs/content/en/templates/robots.md
View File

@@ -1,14 +1,14 @@
---
title: Robots.txt file
linkTitle: Robots.txt
title: robots.txt template
linkTitle: robots.txt templates
description: Hugo can generate a customized robots.txt in the same way as any other template.
categories: [templates]
keywords: [robots,search engines]
keywords: []
menu:
docs:
parent: templates
weight: 230
weight: 230
weight: 170
weight: 170
aliases: [/extras/robots-txt/]
---

14
docs/content/en/templates/rss.md
View File

@@ -2,12 +2,12 @@
title: RSS templates
description: Use the embedded RSS template, or create your own.
categories: [templates]
keywords: [rss,xml,templates]
keywords: []
menu:
docs:
parent: templates
weight: 160
weight: 160
weight: 150
weight: 150
toc: true
---
@@ -70,7 +70,7 @@ Hugo will render this to:
Override Hugo's [embedded RSS template] by creating one or more of your own, following the naming conventions as shown in the [template lookup order].
[embedded RSS template]: {{% eturl rss %}}
[template lookup order]: #template-lookup-order
[template lookup order]: /templates/lookup-order/#rss-templates
For example, to use different templates for home, section, taxonomy, and term pages:
@@ -84,9 +84,3 @@ layouts/
```
RSS templates receive the `.Page` and `.Site` objects in context.
## Template lookup order
The table below shows the RSS template lookup order for the different page kinds. The first listing shows the lookup order when running with a theme (`demoTheme`).
{{< datatable-filtered "output" "layouts" "OutputFormat == rss" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}

30
docs/content/en/templates/section-templates.md → docs/content/en/templates/section.md
View File

@@ -1,21 +1,20 @@
---
title: Section page templates
linkTitle: Section templates
title: Section templates
description: Use section templates to list members of a section.
categories: [templates]
keywords: [lists,sections,templates]
keywords: []
menu:
docs:
parent: templates
weight: 80
weight: 80
toc: true
aliases: [/templates/sections/]
aliases: [/templates/sections/,/templates/section-templates/]
---
## Add content and front matter to section templates
To effectively leverage section page templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages.
To effectively leverage section templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages.
## Section template lookup order
@@ -27,16 +26,15 @@ See [Template Lookup](/templates/lookup-order/).
{{ define "main" }}
<main>
{{ .Content }}
<ul class="contents">
{{ range .Paginator.Pages }}
<li>{{ .Title }}
<div>
{{ partial "summary.html" . }}
</div>
</li>
{{ end }}
</ul>
{{ partial "pagination.html" . }}
{{ $pages := where site.RegularPages "Type" "posts" }}
{{ $paginator := .Paginate $pages }}
{{ range $paginator.Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ template "_internal/pagination.html" . }}
</main>
{{ end }}
{{< /code >}}
@@ -83,8 +81,6 @@ Which then returns the following:
```
[contentorg]: /content-management/organization/
[getpage]: /methods/page/getpage/
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
[`where`]: /functions/collections/where/
[sections]: /content-management/sections/

6
docs/content/en/templates/shortcode-templates.md → docs/content/en/templates/shortcode.md
View File

@@ -3,13 +3,13 @@ title: Create your own shortcodes
linkTitle: Shortcode templates
description: You can extend Hugo's embedded shortcodes by creating your own using the same templating syntax as that for single and list pages.
categories: [templates]
keywords: [shortcodes,templates]
keywords: []
menu:
docs:
parent: templates
weight: 130
weight: 130
aliases: [/functions/get]
aliases: [/templates/shortcode-templates/]
toc: true
---
@@ -104,7 +104,7 @@ The `.Inner` method returns the content between the opening and closing shortcod
```
{{% note %}}
Any shortcode that calls the `.Inner` method must be closed or self-closed. To call a shortcode using the self-closing sytax
Any shortcode that calls the `.Inner` method must be closed or self-closed. To call a shortcode using the self-closing syntax.
```go-html-template
{{</* innershortcode /*/>}}

77
docs/content/en/templates/single-page-templates.md
View File

@@ -1,77 +0,0 @@
---
title: Single page templates
description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template.
categories: [templates]
keywords: [page, templates]
menu:
docs:
parent: templates
weight: 50
weight: 50
toc: true
aliases: [/layout/content/]
---
## Single page template lookup order
See [Template Lookup](/templates/lookup-order/).
## Example single page templates
{{< code file=layouts/posts/single.html >}}
{{ define "main" }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>
<div>
<article id="content">
{{ .Content }}
</article>
</div>
</section>
<aside id="meta">
<div>
<section>
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
<h5 id="wordcount"> {{ .WordCount }} Words</h5>
</section>
{{ with .GetTerms "topics" }}
<ul id="topics">
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}
{{ with .GetTerms "tags" }}
<ul id="tags">
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}
</div>
<div>
{{ with .PrevInSection }}
<a class="previous" href="{{ .RelPermalink }}"> {{ .LinkTitle }}</a>
{{ end }}
{{ with .NextInSection }}
<a class="next" href="{{ .RelPermalink }}"> {{ .LinkTitle }}</a>
{{ end }}
</div>
</aside>
{{ end }}
{{< /code >}}
To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes].
[archetypes]: /content-management/archetypes/
[base templates]: /templates/base/
[content type]: /content-management/types/
[directory structure]: /getting-started/directory-structure/
[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
[`.format` function]: /methods/time/format/
[front matter]: /content-management/front-matter/
[pagetaxonomy]: /templates/taxonomy-templates/#list-terms-assigned-to-a-page
[partials]: /templates/partials/
[section]: /content-management/sections/
[spf13]: https://spf13.com/
[`with`]: /functions/go-template/with/

56
docs/content/en/templates/single.md Normal file
View File

@@ -0,0 +1,56 @@
---
title: Single templates
description: Create a single template to render a single page.
categories: [templates]
keywords: []
menu:
docs:
parent: templates
weight: 70
weight: 70
toc: true
aliases: [/layout/content/,/templates/single-page-templates/]
---
The single template below inherits the site's shell from the [base template].
[base template]: /templates/types/
{{< code file=layouts/_default/single.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}
{{< /code >}}
Review the [template lookup order] to select a template path that provides the desired level of specificity.
[template lookup order]: /templates/lookup-order/#single-templates
The single template below inherits the site's shell from the base template, and renders the page title, creation date, content, and a list of associated terms in the "tags" taxonomy.
{{< code file=layouts/_default/single.html >}}
{{ define "main" }}
<section>
<h1>{{ .Title }}</h1>
{{ with .Date }}
{{ $dateMachine := . | time.Format "2006-01-02T15:04:05-07:00" }}
{{ $dateHuman := . | time.Format ":date_long" }}
<time datetime="{{ $dateMachine }}">{{ $dateHuman }}</time>
{{ end }}
<article>
{{ .Content }}
</article>
<aside>
{{ with .GetTerms "tags" }}
<div>{{ (index . 0).Parent.LinkTitle }}</div>
<ul>
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}
</aside>
</section>
{{ end }}
{{< /code >}}

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

@@ -2,14 +2,14 @@
title: Sitemap templates
description: Hugo provides built-in sitemap templates.
categories: [templates]
keywords: [sitemap,xml,templates]
keywords: []
menu:
docs:
parent: templates
weight: 170
weight: 170
weight: 140
weight: 140
toc: true
aliases: [/layout/sitemap/,/templates/sitemap/]
aliases: [/layout/sitemap/,/templates/sitemap-template/]
---
## Overview

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

@@ -1,285 +0,0 @@
---
title: Taxonomy templates
description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates.
categories: [templates]
keywords: [taxonomies,metadata,front matter,terms,templates]
menu:
docs:
parent: templates
weight: 90
weight: 90
toc: true
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/]
---
Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature.
Hugo provides multiple ways to use taxonomies throughout your project templates:
* Order the way content associated with a taxonomy term is displayed in a [taxonomy template](#taxonomy-templates)
* Order the way the terms for a taxonomy are displayed in a [term template](#term-templates)
* List a single content's taxonomy terms within a [single page template]
## Taxonomy templates
Taxonomy list page templates are lists and therefore have all the methods available to [list pages][lists].
### Taxonomy template lookup order
See [Template Lookup](/templates/lookup-order/).
## Term templates
### Term template lookup order
See [Template Lookup](/templates/lookup-order/).
### Taxonomy methods
{{< list-pages-in-section path=/methods/taxonomy/ >}}
### OrderedTaxonomy
Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order.
```go
[]struct {
Name string
WeightedPages WeightedPages
}
```
Each element of the slice has:
.Term
: The Term used.
.WeightedPages
: A slice of Weighted Pages.
.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.
## WeightedPages
WeightedPages is simply a slice of WeightedPage.
```go
type WeightedPages []WeightedPage
```
.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].
## Displaying custom metadata in taxonomy terms templates
If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by ranging over the page collection returned by the [`Pages`] method:
```go-html-template
<ul>
{{ range .Pages }}
<li>
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
{{ .Params.wikipedia }}
</li>
{{ end }}
</ul>
```
## Order taxonomies
Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
### Order alphabetically example
```go-html-template
<ul>
{{ range .Data.Terms.Alphabetical }}
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
{{ end }}
</ul>
```
## Order content within taxonomies
Hugo uses both `date` and `weight` to order content within taxonomies.
Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to.
When iterating over content within taxonomies, the default sort is the same as that used for section and list pages: first by weight, then by date. This means that if the weights for two pieces of content are the same, then the more recent content will be displayed first.
The default weight for any piece of content is 0. Zero means "does not have a weight", not "has a weight of numerical value zero".
Weights of zero are thus treated specially: if two pages have unequal weights, and one of them is zero, then the zero-weighted page will always appear after the other one, regardless of the other's weight. Zero weights should thus be used with care: for example, if both positive and negative weights are used to extend a sequence in both directions, a zero-weighted page will appear not in the middle of the list, but at the end.
### Assign weight
Content can be assigned weight for each taxonomy that it's assigned to.
{{< code-toggle file=content/example.md fm=true >}}
tags = [ "a", "b", "c" ]
tags_weight = 22
categories = ["d"]
title = "Example"
categories_weight = 44
{{< /code-toggle >}}
The convention is `taxonomyname_weight`.
In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy.
It has also been assigned the weight of 44 when rendering the 'd' category.
With this the same piece of content can appear in different positions in different taxonomies.
Currently taxonomies only support the default ordering of content which is weight -> date.
There are two different templates that the use of taxonomies will require you to provide.
Both templates are covered in detail in the templates section.
A [list template](/templates/lists/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages.
A [taxonomy template](/templates/taxonomy-templates/) is a template used to
generate the list of terms for a given template.
There are four common ways you can display the data in your
taxonomies in addition to the automatic taxonomy pages created by hugo
using the [list templates](/templates/lists/):
1. For a given piece of content, you can list the terms attached
2. For a given piece of content, you can list other content with the same
term
3. You can list all terms for a taxonomy
4. You can list all taxonomies (with their terms)
## List terms assigned to a page
List the terms assigned to a page using the `.Page.GetTerms` method.
To render an unordered list:
```go-html-template
{{ $taxonomy := "tags" }}
{{ with .GetTerms $taxonomy }}
<p>{{ (site.GetPage $taxonomy).LinkTitle }}:</p>
<ul>
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}
```
To render a comma-delimited list:
```go-html-template
{{ $taxonomy := "tags" }}
{{ with .GetTerms $taxonomy }}
<p>
{{ (site.GetPage $taxonomy).LinkTitle }}:
{{ range $k, $_ := . -}}
{{ if $k }}, {{ end }}
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
{{- end }}
</p>
{{ end }}
```
## List content with the same taxonomy term
If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same term. For example:
```go-html-template
<ul>
{{ range .Site.Taxonomies.series.golang }}
<li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
{{ end }}
</ul>
```
## List all content in a given taxonomy
This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.
```go-html-template
<section id="menu">
<ul>
{{ range $term, $taxonomy := .Site.Taxonomies.featured }}
<li>{{ $term }}</li>
<ul>
{{ range $taxonomy.Pages }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}
</ul>
</section>
```
## Render a site's taxonomies
The following example displays all terms in a site's tags taxonomy:
```go-html-template
<ul>
{{ range .Site.Taxonomies.tags }}
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
{{ end }}
</ul>
```
This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
{{< code file=layouts/partials/all-taxonomies.html >}}
{{ with .Site.Taxonomies }}
{{ $numberOfTerms := 0 }}
{{ range $taxonomy, $terms := . }}
{{ $numberOfTerms = len . | add $numberOfTerms }}
{{ end }}
{{ if gt $numberOfTerms 0 }}
<ul>
{{ range $taxonomy, $terms := . }}
{{ with $terms }}
<li>
<a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
<ul>
{{ range $term, $weightedPages := . }}
<li>
<a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
<ul>
{{ range $weightedPages }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
</li>
{{ end }}
</ul>
</li>
{{ end }}
{{ end }}
</ul>
{{ end }}
{{ end }}
{{< /code >}}
[`Pages`]: /methods/page/pages/
[getpage]: /methods/page/getpage/
[lists]: /templates/lists/
[renderlists]: /templates/lists/
[single page template]: /templates/single-page-templates/

176
docs/content/en/templates/taxonomy.md Normal file
View File

@@ -0,0 +1,176 @@
---
title: Taxonomy templates
description: Create a taxonomy template to render a list of terms.
categories: [templates]
keywords: []
menu:
docs:
parent: templates
weight: 90
weight: 90
toc: true
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy-templates/]
---
The [taxonomy] template below inherits the site's shell from the [base template], and renders a list of [terms] in the current taxonomy.
[taxonomy]: /getting-started/glossary/#taxonomy
[terms]: /getting-started/glossary/#term
[base template]: /templates/types/
{{< code file=layouts/_default/taxonomy.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
Review the [template lookup order] to select a template path that provides the desired level of specificity.
[template lookup order]: /templates/lookup-order/#taxonomy-templates
In the example above, the taxonomy and term will be capitalized if their respective pages are not backed by files. You can disable this in your site configuration:
{{< code-toggle file=hugo >}}
capitalizeListTitles = false
{{< /code-toggle >}}
## Data object
Use these methods on the `Data` object within a taxonomy template.
Singular
: (`string`) Returns the singular name of the taxonomy.
```go-html-template
{{ .Data.Singular }} → tag
```
Plural
: (`string`) Returns the plural name of the taxonomy.
```go-html-template
{{ .Data.Plural }} → tags
```
Terms
: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages] associated with each term.
[weighted pages]: /getting-started/glossary/#weighted-page
```go-html-template
{{ $taxonomyObject := .Data.Terms }}
```
Once we have the `Taxonomy` object, we can call any of its [methods], allowing us to sort alphabetically or by term count.
[methods]: /methods/taxonomy/
## Sort alphabetically
The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list alphabetically by term, and displays the number of pages associated with each term.
{{< code file=layouts/_default/taxonomy.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Data.Terms.Alphabetical }}
<h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
{{ end }}
{{ end }}
{{< /code >}}
## Sort by term count
The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list by the number of pages associated with each term, and displays the number of pages associated with each term.
{{< code file=layouts/_default/taxonomy.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Data.Terms.ByCount }}
<h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
{{ end }}
{{ end }}
{{< /code >}}
## Include content links
The [`Alphabetical`] and [`ByCount`] methods used in the previous examples return an [ordered taxonomy], so we can also list the content to which each term is assigned.
[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy
[`Alphabetical`]: /methods/taxonomy/alphabetical/
[`ByCount`]: /methods/taxonomy/bycount/
The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list by the number of pages associated with each term, displays the number of pages associated with each term, then lists the content to which each term is assigned.
{{< code file=layouts/_default/taxonomy.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Data.Terms.ByCount }}
<h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
<ul>
{{ range .WeightedPages }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}
{{ end }}
{{< /code >}}
## Display metadata
Display metadata about each term by creating a corresponding branch bundle in the content directory.
For example, create an "authors" taxonomy:
{{< code-toggle file=hugo >}}
[taxonomies]
author = 'authors'
{{< /code-toggle >}}
Then create content with one [branch bundle] for each term:
[branch bundle]: /getting-started/glossary/#branch-bundle
```text
content/
└── authors/
├── jsmith/
│ ├── _index.md
│ └── portrait.jpg
└── rjones/
├── _index.md
└── portrait.jpg
```
Then add front matter to each term page:
{{< code-toggle file=content/authors/jsmith/_index.md fm=true >}}
title = "John Smith"
affiliation = "University of Chicago"
{{< /code-toggle >}}
Then create a taxonomy template specific to the "authors" taxonomy:
{{< code file=layouts/authors/taxonomy.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Data.Terms.Alphabetical }}
<h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2>
<p>Affiliation: {{ .Page.Params.Affiliation }}</p>
{{ with .Page.Resources.Get "portrait.jpg" }}
{{ with .Fill "100x100" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="portrait">
{{ end }}
{{ end }}
{{ end }}
{{ end }}
{{< /code >}}
In the example above we list each author including their affiliation and portrait.

115
docs/content/en/templates/term.md Normal file
View File

@@ -0,0 +1,115 @@
---
title: Term templates
description: Create a term template to render a list of pages associated with the current term.
categories: [templates]
keywords: []
menu:
docs:
parent: templates
weight: 100
weight: 100
toc: true
---
The [term] template below inherits the site's shell from the [base template], and renders a list of pages associated with the current term.
[term]: /getting-started/glossary/#term
[base template]: /templates/types/
{{< code file=layouts/_default/term.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
Review the [template lookup order] to select a template path that provides the desired level of specificity.
[template lookup order]: /templates/lookup-order/#taxonomy-templates
In the example above, the term will be capitalized if its respective page is not backed by a file. You can disable this in your site configuration:
{{< code-toggle file=hugo >}}
capitalizeListTitles = false
{{< /code-toggle >}}
## Data object
Use these methods on the `Data` object within a term template.
Singular
: (`string`) Returns the singular name of the taxonomy.
```go-html-template
{{ .Data.Singular }} → tag
```
Plural
: (`string`) Returns the plural name of the taxonomy.
```go-html-template
{{ .Data.Plural }} → tags
```
Term
: (`string`) Returns the name of the term.
```go-html-template
{{ .Data.Term }} → fiction
```
## Display metadata
Display metadata about each term by creating a corresponding branch bundle in the content directory.
For example, create an "authors" taxonomy:
{{< code-toggle file=hugo >}}
[taxonomies]
author = 'authors'
{{< /code-toggle >}}
Then create content with one [branch bundle] for each term:
[branch bundle]: /getting-started/glossary/#branch-bundle
```text
content/
└── authors/
├── jsmith/
│ ├── _index.md
│ └── portrait.jpg
└── rjones/
├── _index.md
└── portrait.jpg
```
Then add front matter to each term page:
{{< code-toggle file=content/authors/jsmith/_index.md fm=true >}}
title = "John Smith"
affiliation = "University of Chicago"
{{< /code-toggle >}}
Then create a term template specific to the "authors" taxonomy:
{{< code file=layouts/authors/term.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
<p>Affiliation: {{ .Params.affiliation }}</p>
{{ with .Resources.Get "portrait.jpg" }}
{{ with .Fill "100x100" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="portrait">
{{ end }}
{{ end }}
{{ .Content }}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
In the example above we display the author with their affiliation and portrait, then a list of associated content.

284
docs/content/en/templates/types/index.md Normal file
View File

@@ -0,0 +1,284 @@
---
title: Template types
linkTitle: Template types
description: Create templates of different types to render your content, resources, and data.
categories: [templates]
keywords: []
menu:
docs:
parent: templates
weight: 30
weight: 30
toc: true
aliases: ['/templates/lists/']
---
[![structural diagram of a website](site-hierarchy.svg)](site-hierarchy.svg)
## Structure
Create templates in the layouts directory in the root of your project.
Although your site may not require each of these templates, the example below is typical for a site of medium complexity.
```text
layouts/
├── _default/
│ ├── _markup/
│ │ ├── render-image.html <-- render hook
│ │ └── render-link.html <-- render hook
│ ├── baseof.html
│ ├── home.html
│ ├── section.html
│ ├── single.html
│ ├── taxonomy.html
│ └── term.html
├── articles/
│ └── card.html <-- content view
├── partials/
│ ├── footer.html
│ └── header.html
└── shortcodes/
├── audio.html
└── video.html
```
Hugo's [template lookup order] determines the template path, allowing you to create unique templates for any page.
[template lookup order]: /templates/lookup-order/
{{% note %}}
You must have thorough understanding of the [template lookup order] when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format.
[template lookup order]: /templates/lookup-order/
{{% /note %}}
The purpose of each template type is described below.
## Base
Base templates reduce duplicate code by wrapping other templates within a shell.
For example, the base template below calls the [partial] function to include partial templates for the `head`, `header`, and `footer` elements of each page, and it uses the [block] function to include `home`, `single`, `section`, `taxonomy`, and `term` templates within the `main` element of each page.
[block]: /functions/go-template/block/
[partial]: /functions/partials/include/
{{< code file=layouts/_default/baseof.html >}}
<!DOCTYPE html>
<html lang="{{ or site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
<head>
{{ partial "head.html" . }}
</head>
<body>
<header>
{{ partial "header.html" . }}
</header>
<main>
{{ block "main" . }}{{ end }}
</main>
<footer>
{{ partial "footer.html" . }}
</footer>
</body>
</html>
{{< /code >}}
Learn more about [base templates](/templates/base/).
## Home
A home template renders your site's home page. For a single page site this is the only required template.
For example, the home template below inherits the site's shell from the base template, and renders the home page content with a list of pages.
{{< code file=layouts/_default/home.html >}}
{{ define "main" }}
{{ .Content }}
{{ range site.RegularPages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
{{% include "templates/_common/filter-sort-group.md" %}}
Learn more about [home templates](/templates/home/).
## Single
A single template renders a single page.
For example, the single template below inherits the site's shell from the base template, and renders the title and content of each page.
{{< code file=layouts/_default/single.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}
{{< /code >}}
Learn more about [single templates](/templates/single/).
## Section
A section template typically renders a list of pages within a section.
For example, the section template below inherits the site's shell from the base template, and renders a list of pages in the current section.
{{< code file=layouts/_default/section.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
{{% include "templates/_common/filter-sort-group.md" %}}
Learn more about [section templates](/templates/section/).
## Taxonomy
A taxonomy template renders a list of terms in a [taxonomy].
[taxonomy]: /getting-started/glossary/#taxonomy
For example, the taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy.
{{< code file=layouts/_default/taxonomy.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
{{% include "templates/_common/filter-sort-group.md" %}}
Learn more about [taxonomy templates](/templates/taxonomy/).
## Term
A term template renders a list of pages associated with a [term].
[term]: /getting-started/glossary/#term
For example, the term template below inherits the site's shell from the base template, and renders a list of pages associated with the current term.
{{< code file=layouts/_default/term.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
{{% include "templates/_common/filter-sort-group.md" %}}
Learn more about [term templates](/templates/term/).
## Partial
A partial template is typically used to render a component of your site, though you may also create partial templates that return values.
{{% note %}}
Unlike other template types, you cannot create partial templates to target a particular page kind, content type, section, language, or output format. Partial templates do not follow Hugo's [template lookup order].
[template lookup order]: /templates/lookup-order/
{{% /note %}}
For example, the partial template below renders copyright information.
{{< code file=layouts/partials/footer.html >}}
<p>Copyright {{ now.Year }}. All rights reserved.</p>
{{< /code >}}
Learn more about [partial templates](/templates/partial/).
## Content view
A content view template is similar to a partial template, invoked by calling the [`Render`] method on a `Page` object. Unlike partial templates, content view templates:
- Automatically inherit the context of the current page
- Follow a lookup order allowing you to target a given content type or section
[`Render`]: /methods/page/render/
For example, the home template below inherits the site's shell from the base template, and renders a card component for each page within the "articles" section of your site.
{{< code file=layouts/_default/home.html >}}
{{ define "main" }}
{{ .Content }}
<ul>
{{ range where site.RegularPages "Section" "articles" }}
{{ .Render "card" }}
{{ end }}
</ul>
{{ end }}
{{< /code >}}
{{< code file=layouts/articles/card.html >}}
<div class="card">
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ .Summary }}
</div>
{{< /code >}}
Learn more about [content view templates](/templates/content-view/).
## Render hook
A render hook template overrides the conversion of Markdown to HTML.
For example, the render hook template below adds a `rel` attribute to external links.
{{< code file=layouts/_default/_markup/render-link.html >}}
{{- $u := urls.Parse .Destination -}}
<a href="{{ .Destination | safeURL }}"
{{- with .Title }} title="{{ . }}"{{ end -}}
{{- if $u.IsAbs }} rel="external"{{ end -}}
>
{{- with .Text | safeHTML }}{{ . }}{{ end -}}
</a>
{{- /* chomp trailing newline */ -}}
{{< /code >}}
Learn more about [render hook templates](/render-hooks/).
## Shortcode
A shortcode template is used to render a component of your site. Unlike partial templates, shortcode templates are called from content pages.
For example, the shortcode template below renders an audio element from a [global resource].
[global resource]: /getting-started/glossary/#global-resource
{{< code file=layouts/shortcodes/audio.html >}}
{{ with resources.Get (.Get "src") }}
<audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
{{ end }}
{{< /code >}}
Call the shortcode from your content page:
{{< code file=content/example.md >}}
{{</* audio src="audio/test.mp3" */>}}
{{< /code >}}
Learn more about [shortcode templates](/templates/shortcode/).
## Other
Use other specialized templates to create:
- [Sitemaps](/templates/sitemap)
- [RSS feeds](/templates/rss/)
- [404 error pages](/templates/404/)
- [robots.txt files](/templates/robots/)

0
docs/content/en/templates/lists/site-hierarchy.svg → docs/content/en/templates/types/site-hierarchy.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 193 KiB

After

Width:  |  Height:  |  Size: 193 KiB