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

Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
parent 208a0de6c3 5be51ac3db
commit 653f1c1d46
987 changed files with 12379 additions and 14083 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -2,18 +2,14 @@
title: Custom 404 page
linkTitle: 404 templates
description: Create a template to render a 404 error page.
categories: [templates]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 160
weight: 160
weight: 190
---
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:
{{< code file=layouts/404.html >}}
```go-html-template {file="layouts/404.html"}
{{ define "main" }}
<h1>404 Not Found</h1>
<p>The page you requested cannot be found.</p>
@@ -23,7 +19,7 @@ To render a 404 error page in the root of your site, create a 404 template in th
</a>
</p>
{{ end }}
{{< /code >}}
```
For multilingual sites, add the language key to the file name:

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

@@ -1,13 +0,0 @@
---
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
View File

@@ -1,9 +0,0 @@
---
_comment: 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 %}}

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

@@ -1,16 +1,8 @@
---
title: Templates
description: Create templates to render your content, resources, and data.
categories: []
keywords: []
menu:
docs:
identifier: templates-in-this-section
parent: templates
weight: 10
weight: 10
aliases: [/templates/overview/,/templates/content]
---
A template is an HTML file with [template actions](g), 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.

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

@@ -1,14 +1,9 @@
---
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]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 50
weight: 50
toc: true
weight: 40
aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
---
@@ -26,7 +21,7 @@ See [Template Lookup Order](/templates/lookup-order/) for details and examples.
The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order.
{{< code file=layouts/_default/baseof.html >}}
```go-html-template {file="layouts/_default/baseof.html"}
<!DOCTYPE html>
<html>
<head>
@@ -46,13 +41,13 @@ The following defines a simple base template at `_default/baseof.html`. As a def
{{ end }}
</body>
</html>
{{< /code >}}
```
## Override the base template
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 >}}
```go-html-template {file="layouts/_default/list.html"}
{{ define "main" }}
<h1>Posts</h1>
{{ range .Pages }}
@@ -62,25 +57,25 @@ The default list template will inherit all of the code defined above and can the
</article>
{{ end }}
{{ end }}
{{< /code >}}
This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
{{% note %}}
Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
```go-html-template
<!-- Seemingly harmless HTML comment..that will break your layout at build -->
{{ define "main" }}
...your code here
{{ end }}
```
[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 template]:
This replaces the contents of our (basically empty) `main` block with something useful for the list template. In this case, we didn't define a `title` block, so the contents from our base template remain unchanged in lists.
{{< code file=layouts/_default/single.html >}}
> [!warning]
> Only [template comments] are allowed outside a block's `define` and `end` statements. Avoid placing any other text, including HTML comments, outside these boundaries. Doing so will cause rendering issues, potentially resulting in a blank page. See the example below.
```go-html-template {file="layouts/_default/do-not-do-this.html"}
<div>This div element broke your template.</div>
{{ define "main" }}
<h2>{{ .Title }}</h2>
{{ .Content }}
{{ end }}
<!-- An HTML comment will break your template too. -->
```
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]:
```go-html-template {file="layouts/_default/single.html"}
{{ define "title" }}
<!-- This will override the default value set in baseof.html; i.e., "{{ .Site.Title }}" in the original example-->
{{ .Title }} &ndash; {{ .Site.Title }}
@@ -89,6 +84,7 @@ The following shows how you can override both the `"main"` and `"title"` block a
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}
{{< /code >}}
```
[single template]: /templates/types/#single
[template comments]: /templates/introduction/#comments

31
docs/content/en/templates/content-view.md
View File

@@ -1,21 +1,16 @@
---
title: Content view templates
description: Hugo can render alternative views of your content, useful in list and summary views.
categories: [templates]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 120
weight: 120
toc: true
weight: 110
aliases: [/templates/views/]
---
The following are common use cases for content views:
* 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.
- 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
@@ -46,11 +41,11 @@ The following is the lookup order for content views ordered by specificity.
## Example: content view inside a list
### `list.html`
### 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:
{{< code file=layouts/_default/list.html >}}
```go-html-template {file="layouts/_default/list.html"}
<main id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
@@ -59,13 +54,13 @@ In this example, `.Render` is passed into the template to call the [render funct
{{ end }}
</div>
</main>
{{< /code >}}
```
### `summary.html`
### summary.html
Hugo passes the `Page` object to the following `summary.html` view template.
{{< code file=layouts/_default/summary.html >}}
```go-html-template {file="layouts/_default/summary.html"}
<article class="post">
<header>
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
@@ -76,18 +71,18 @@ Hugo passes the `Page` object to the following `summary.html` view template.
<a href='{{ .RelPermalink }}'>Read&nbsp;more&nbsp;&raquo;</a>
</footer>
</article>
{{< /code >}}
```
### `li.html`
### li.html
Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
{{< code file=layouts/_default/li.html >}}
```go-html-template {file="layouts/_default/li.html"}
<li>
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{< /code >}}
```
[render]: /methods/page/render/
[single template]: /templates/types/#single

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

@@ -1,33 +1,21 @@
---
title: Embedded templates
description: Hugo provides embedded templates for common use cases.
categories: [templates]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 200
weight: 200
toc: true
weight: 170
aliases: [/templates/internal]
---
## Disqus
{{% note %}}
To override Hugo's embedded Disqus 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 "disqus.html" . }}`
[`partial`]: /functions/partials/include/
[source code]: {{% eturl disqus %}}
{{% /note %}}
> [!note]
> To override Hugo's embedded Disqus template, copy the [source code]({{% eturl disqus %}}) to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
>
> `{{ partial "disqus.html" . }}`
Hugo includes an embedded template for [Disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up] for the free service.
[Disqus]: https://disqus.com
[signing up]: https://disqus.com/profile/signup/
To include the embedded template:
```go-html-template
@@ -38,7 +26,7 @@ To include the embedded template:
To use Hugo's Disqus template, first set up a single configuration value:
{{< code-toggle file="hugo" >}}
{{< code-toggle file=hugo >}}
[services.disqus]
shortname = 'your-disqus-shortname'
{{</ code-toggle >}}
@@ -66,19 +54,13 @@ disable
## Google Analytics
{{% note %}}
To override Hugo's embedded Google Analytics 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 "google_analytics.html" . }}`
[`partial`]: /functions/partials/include/
[source code]: {{% eturl google_analytics %}}
{{% /note %}}
> [!note]
> To override Hugo's embedded Google Analytics template, copy the [source code]({{% eturl google_analytics %}}) to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
>
> `{{ partial "google_analytics.html" . }}`
Hugo includes an embedded template supporting [Google Analytics 4].
[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
To include the embedded template:
```go-html-template
@@ -110,14 +92,10 @@ respectDoNotTrack
## Open Graph
{{% note %}}
To override Hugo's embedded Open Graph 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 "opengraph.html" . }}`
[`partial`]: /functions/partials/include/
[source code]: {{% eturl opengraph %}}
{{% /note %}}
> [!note]
> To override Hugo's embedded Open Graph template, copy the [source code]({{% eturl opengraph %}}) to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
>
> `{{ partial "opengraph.html" . }}`
Hugo includes an embedded template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph.
This format is used for Facebook and some other sites.
@@ -169,19 +147,13 @@ If using YouTube this will produce a og:video tag like `<meta property="og:video
## Schema
{{% note %}}
To override Hugo's embedded Schema 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 "schema.html" . }}`
[`partial`]: /functions/partials/include/
[source code]: {{% eturl schema %}}
{{% /note %}}
> [!note]
> To override Hugo's embedded Schema template, copy the [source code]({{% eturl schema %}}) to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
>
> `{{ partial "schema.html" . }}`
Hugo includes an embedded template to render [microdata] `meta` elements within the `head` element of your templates.
[microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata
To include the embedded template:
```go-html-template
@@ -190,14 +162,10 @@ To include the embedded template:
## X (Twitter) Cards
{{% note %}}
To override Hugo's embedded Twitter Cards 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 "twitter_cards.html" . }}`
[`partial`]: /functions/partials/include/
[source code]: {{% eturl twitter_cards %}}
{{% /note %}}
> [!note]
> To override Hugo's embedded Twitter Cards template, copy the [source code]({{% eturl twitter_cards %}}) to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
>
> `{{ partial "twitter_cards.html" . }}`
Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards),
metadata used to attach rich media to Tweets linking to your site.
@@ -218,21 +186,21 @@ Hugo's X (Twitter) Card template is configured using a mix of configuration sett
description = "Text about my cool site"
{{</ code-toggle >}}
{{< code-toggle file=content/blog/my-post.md >}}
{{< code-toggle file=content/blog/my-post.md fm=true >}}
title = "Post title"
description = "Text about this post"
images = ["post-cover.png"]
{{</ code-toggle >}}
If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata.
If no image resources with those names are found, the images defined in the [site config](/getting-started/configuration/) are used instead.
If no image resources with those names are found, the images defined in the [site config](/configuration/) are used instead.
If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`.
Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given.
Set the value of `twitter:site` in your site configuration:
{{< code-toggle file="hugo" copy=false >}}
{{< code-toggle file=hugo >}}
[params.social]
twitter = "GoHugoIO"
{{</ code-toggle >}}
@@ -242,3 +210,9 @@ NOTE: The `@` will be added for you
```html
<meta name="twitter:site" content="@GoHugoIO"/>
```
[`partial`]: /functions/partials/include/
[Disqus]: https://disqus.com
[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
[microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata
[signing up]: https://disqus.com/profile/signup/

30
docs/content/en/templates/home.md
View File

@@ -1,41 +1,33 @@
---
title: Home page 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]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 60
weight: 60
toc: true
weight: 50
aliases: [/layout/homepage/,/templates/homepage-template/,/templates/homepage/]
---
## Introduction
A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages.
A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages.
{{< code file=layouts/_default/home.html >}}
```go-html-template {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" %}}
{{% include "/_common/filter-sort-group.md" %}}
## Lookup order
Hugo's [template lookup order] determines the template path, allowing you to create unique templates for any page.
[template lookup order]: /templates/lookup-order/#home-templates
{{% 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.
{{% /note %}}
> [!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.
## Content and front matter
@@ -53,7 +45,7 @@ params:
The home page template below inherits the site's shell from the base template, renders the subtitle and content as defined in the&nbsp;`_index.md`&nbsp;file, then renders of list of the site's [regular pages](g).
{{< code file=layouts/_default/home.html >}}
```go-html-template {file="layouts/_default/home.html"}
{{ define "main" }}
<h3>{{ .Params.Subtitle }}</h3>
{{ .Content }}
@@ -61,4 +53,6 @@ The home page template below inherits the site's shell from the base template, r
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
```
[template lookup order]: /templates/lookup-order/#home-templates

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

@@ -1,34 +1,22 @@
---
title: Introduction to templating
linkTitle: Introduction
description: Create templates to render your content, resources, and data.
categories: [templates,fundamentals]
description: An introduction to Hugo's templating syntax.
categories: []
keywords: []
menu:
docs:
identifier: templates-introduction
parent: templates
weight: 20
weight: 20
toc: true
weight: 10
---
A template is a file in the `layouts` directory of a project, theme, or module. Templates use [variables] , [functions], and [methods] to transform your content, resources, and data into a published page.
{{% glossary-term template %}}
[functions]: /functions/
[methods]: /methods/
[variables]: #variables
Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page.
{{% note %}}
Hugo uses Go's [text/template] and [html/template] packages.
The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection.
By default, Hugo uses the html/template package when rendering HTML files.
[text/template]: https://pkg.go.dev/text/template
[html/template]: https://pkg.go.dev/html/template
{{% /note %}}
> [!note]
> Hugo uses Go's [text/template] and [html/template] packages.
>
> The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection.
>
> By default, Hugo uses the html/template package when rendering HTML files.
For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph.
@@ -38,9 +26,7 @@ For example, this HTML template initializes the `$v1` and `$v2` variables, then
<p>The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.</p>
```
While HTML templates are the most common, you can create templates for any [output format] including CSV, JSON, RSS, and plain text.
[output format]: /templates/output-formats/
While HTML templates are the most common, you can create templates for any [output format](g) including CSV, JSON, RSS, and plain text.
## Context
@@ -52,21 +38,15 @@ For example, a template for a single page receives a `Page` object, and the `Pag
Within a template, the dot (`.`) represents the current context.
{{< code file=layouts/_default/single.html >}}
```go-html-template {file="layouts/_default/single.html"}
<h2>{{ .Title }}</h2>
{{< /code >}}
```
In the example above the dot represents the `Page` object, and we call its [`Title`] method to return the title as defined in [front matter].
[front matter]: /content-management/front-matter/
[`Title`]: /methods/page/title
The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we rebind the context to another value or object within [`range`] or [`with`] blocks.
[`range`]: /functions/go-template/range/
[`with`]: /functions/go-template/with/
{{< code file=layouts/_default/single.html >}}
```go-html-template {file="layouts/_default/single.html"}
<h2>{{ .Title }}</h2>
{{ range slice "foo" "bar" }}
@@ -76,7 +56,7 @@ The current context may change within a template. For example, at the top of a t
{{ with "baz" }}
<p>{{ . }}</p>
{{ end }}
{{< /code >}}
```
In the example above, the context changes as we `range` through the [slice](g) of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to:
@@ -91,11 +71,11 @@ In the example above, the context changes as we `range` through the [slice](g) o
Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot:
{{< code file=layouts/_default/single.html >}}
```go-html-template {file="layouts/_default/single.html"}
{{ with "foo" }}
<p>{{ $.Title }} - {{ . }}</p>
{{ end }}
{{< /code >}}
```
Hugo renders this to:
@@ -103,9 +83,8 @@ Hugo renders this to:
<p>My Page Title - foo</p>
```
{{% note %}}
Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context.
{{% /note %}}
> [!note]
> Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context.
## Actions
@@ -113,12 +92,12 @@ In the examples above the paired opening and closing braces represent the beginn
A template action may contain literal values ([boolean](g), [string](g), [integer](g), and [float](g)), variables, functions, and methods.
{{< code file=layouts/_default/single.html >}}
```go-html-template {file="layouts/_default/single.html"}
{{ $convertToLower := true }}
{{ if $convertToLower }}
<h2>{{ strings.ToLower .Title }}</h2>
{{ end }}
{{< /code >}}
```
In the example above:
@@ -140,12 +119,12 @@ Hugo renders the above to:
Notice the blank lines and indentation in the previous example? Although irrelevant in production when you typically minify the output, you can remove the adjacent whitespace by using template action delimiters with hyphens:
{{< code file=layouts/_default/single.html >}}
```go-html-template {file="layouts/_default/single.html"}
{{- $convertToLower := true -}}
{{- if $convertToLower -}}
<h2>{{ strings.ToLower .Title }}</h2>
{{- end -}}
{{< /code >}}
```
Hugo renders this to:
@@ -178,9 +157,8 @@ These are also equivalent:
{{ 5 | add 2 | mul 6 }} → 42
```
{{% note %}}
Remember that the piped value becomes the final argument to the function or method to which you are piping.
{{% /note %}}
> [!note]
> Remember that the piped value becomes the final argument to the function or method to which you are piping.
### Line splitting
@@ -225,8 +203,6 @@ Variables initialized inside of an `if`, `range`, or `with` block are scoped to
With variables that represent a slice or map, use the [`index`] function to return the desired value.
[`index`]: /functions/collections/indexfunction/
```go-html-template
{{ $slice := slice "foo" "bar" "baz" }}
{{ index $slice 2 }} → baz
@@ -235,9 +211,8 @@ With variables that represent a slice or map, use the [`index`] function to retu
{{ index $map "c" }} → baz
```
{{% note %}}
Slices and arrays are zero-based; element 0 is the first element.
{{% /note %}}
> [!note]
> Slices and arrays are zero-based; element 0 is the first element.
With variables that represent a map or object, [chain](g) identifiers to return the desired value or to access the desired method.
@@ -249,9 +224,8 @@ With variables that represent a map or object, [chain](g) identifiers to return
{{ $homePage.Title }} → My Homepage
```
{{% note %}}
As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore.
{{% /note %}}
> [!note]
> As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore.
## Functions
@@ -259,12 +233,8 @@ Used within a template action, a function takes one or more arguments and return
Go's text/template and html/template packages provide a small set of functions, operators, and statements for general use. See the [go-templates] section of the function documentation for details.
[go-templates]: /functions/go-template/
Hugo provides hundreds of custom [functions] categorized by namespace. For example, the `strings` namespace includes these and other functions:
[functions]: /functions
Function|Alias
:--|:--
[`strings.ToLower`](/functions/strings/tolower)|`lower`
@@ -285,10 +255,6 @@ Used within a template action and associated with an object, a method takes zero
The most commonly accessed objects are the [`Page`] and [`Site`] objects. This is a small sampling of the [methods] available to each object.
[`Site`]: /methods/site/
[`Page`]: /methods/page/
[methods]: /methods/
Object|Method|Description
:--|:--|:--
`Page`|[`Date`](methods/page/date/)|Returns the date of the given page.
@@ -300,34 +266,31 @@ Object|Method|Description
Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context].
[current context]: #current-context
{{< code file=layouts/_default/single.html >}}
```go-html-template {file="layouts/_default/single.html"}
{{ .Site.Title }} → My Site Title
{{ .Page.Title }} → My Page Title
{{< /code >}}
```
The context passed into most templates is a `Page` object, so this is equivalent to the previous example:
{{< code file=layouts/_default/single.html >}}
```go-html-template {file="layouts/_default/single.html"}
{{ .Site.Title }} → My Site Title
{{ .Title }} → My Page Title
{{< /code >}}
```
Some methods take an argument. Separate the argument from the method with a space. For example:
{{< code file=layouts/_default/single.html >}}
```go-html-template {file="layouts/_default/single.html"}
{{ $page := .Page.GetPage "/books/les-miserables" }}
{{ $page.Title }} → Les Misérables
{{< /code >}}
```
## Comments
{{% note %}}
Do not attempt to use HTML comment delimiters to comment out template code.
Hugo strips HTML comments when rendering a page, but first evaluates any template code within the HTML comment delimiters. Depending on the template code within the HTML comment delimiters, this could cause unexpected results or fail the build.
{{% /note %}}
> [!note]
> Do not attempt to use HTML comment delimiters to comment out template code.
>
> Hugo strips HTML comments when rendering a page, but first evaluates any template code within the HTML comment delimiters. Depending on the template code within the HTML comment delimiters, this could cause unexpected results or fail the build.
Template comments are similar to template actions. Paired opening and closing braces represent the beginning and end of a comment. For example:
@@ -353,8 +316,6 @@ You may not nest one comment inside of another.
To render an HTML comment, pass a string through the [`safeHTML`] template function. For example:
[`safeHTML`]: /functions/safe/html
```go-html-template
{{ "<!-- I am an HTML comment. -->" | safeHTML }}
{{ printf "<!-- This is the %s site. -->" .Site.Title | safeHTML }}
@@ -364,8 +325,6 @@ To render an HTML comment, pass a string through the [`safeHTML`] template funct
Use the [`template`] function to include one or more of Hugo's [embedded templates]:
[embedded templates]: /templates/embedded/
```go-html-template
{{ template "_internal/google_analytics.html" . }}
{{ template "_internal/opengraph" . }}
@@ -374,14 +333,8 @@ Use the [`template`] function to include one or more of Hugo's [embedded templat
{{ template "_internal/twitter_cards.html" . }}
```
[`partial`]: /functions/partials/include/
[`partialCached`]: /functions/partials/includecached/
[`template`]: /functions/go-template/template/
Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:
[partial templates]: /templates/partial
```go-html-template
{{ partial "breadcrumbs.html" . }}
{{ partialCached "css.html" . }}
@@ -389,24 +342,17 @@ Use the [`partial`] or [`partialCached`] function to include one or more [partia
Create your partial templates in the layouts/partials directory.
{{% note %}}
In the examples above, note that we are passing the current context (the dot) to each of the templates.
{{% /note %}}
> [!note]
> In the examples above, note that we are passing the current context (the dot) to each of the templates.
## Examples
This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions], [methods], and [templates] documentation for specific examples.
[templates]: /templates/
### Conditional blocks
See documentation for [`if`], [`else`], and [`end`].
[`if`]: /functions/go-template/if/
[`else`]: /functions/go-template/else/
[`end`]: /functions/go-template/end/
```go-html-template
{{ $var := 42 }}
{{ if eq $var 6 }}
@@ -424,9 +370,6 @@ See documentation for [`if`], [`else`], and [`end`].
See documentation for [`and`] and [`or`].
[`and`]: /functions/go-template/and
[`or`]: /functions/go-template/or
```go-html-template
{{ $v1 := true }}
{{ $v2 := false }}
@@ -448,8 +391,6 @@ See documentation for [`and`] and [`or`].
See documentation for [`range`], [`else`], and [`end`].
[`range`]: /functions/go-template/range/
```go-html-template
{{ $s := slice "foo" "bar" "baz" }}
{{ range $s }}
@@ -461,8 +402,6 @@ See documentation for [`range`], [`else`], and [`end`].
Use the [`seq`] function to loop a specified number of times:
[`seq`]: /functions/collections/seq
```go-html-template
{{ $total := 0 }}
{{ range seq 4 }}
@@ -475,8 +414,6 @@ Use the [`seq`] function to loop a specified number of times:
See documentation for [`with`], [`else`], and [`end`].
[`with`]: /functions/go-template/with/
```go-html-template
{{ $var := "foo" }}
{{ with $var }}
@@ -534,21 +471,65 @@ Access the custom site parameters by chaining the identifiers:
See documentation for the [`Params`](/methods/page/params/) method on a `Page` object.
With this front matter:
By way of example, consider this front matter:
{{< code-toggle file=content/news/annual-conference.md >}}
{{< code-toggle file=content/annual-conference.md fm=true >}}
title = 'Annual conference'
date = 2023-10-17T15:11:37-07:00
[params]
display_related = true
key-with-hyphens = 'must use index function'
[params.author]
email = 'jsmith@example.org'
name = 'John Smith'
{{< /code-toggle >}}
Access the custom page parameters by chaining the identifiers:
The `title` and `date` fields are standard [front matter fields], while the other fields are user-defined.
Access the custom fields by [chaining](g) the [identifiers](g) when needed:
```go-html-template
{{ .Params.display_related }} → true
{{ .Params.author.email }} → jsmith@example.org
{{ .Params.author.name }} → John Smith
```
In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
```go-html-template
{{ index .Params "key-with-hyphens" }} → must use index function
```
[`and`]: /functions/go-template/and
[`else`]: /functions/go-template/else/
[`end`]: /functions/go-template/end/
[`if`]: /functions/go-template/if/
[`index`]: /functions/collections/indexfunction/
[`index`]: /functions/collections/indexfunction/
[`or`]: /functions/go-template/or
[`Page`]: /methods/page/
[`partial`]: /functions/partials/include/
[`partialCached`]: /functions/partials/includecached/
[`range`]: /functions/go-template/range/
[`range`]: /functions/go-template/range/
[`safeHTML`]: /functions/safe/html
[`seq`]: /functions/collections/seq
[`Site`]: /methods/site/
[`template`]: /functions/go-template/template/
[`Title`]: /methods/page/title
[`with`]: /functions/go-template/with/
[`with`]: /functions/go-template/with/
[current context]: #current-context
[embedded templates]: /templates/embedded/
[front matter]: /content-management/front-matter/
[front matter fields]: /content-management/front-matter/#fields
[functions]: /functions/
[functions]: /functions
[go-templates]: /functions/go-template/
[html/template]: https://pkg.go.dev/html/template
[methods]: /methods/
[methods]: /methods/
[partial templates]: /templates/partial
[templates]: /templates/
[text/template]: https://pkg.go.dev/text/template
[variables]: #variables

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

@@ -2,14 +2,9 @@
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]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 40
weight: 40
toc: true
weight: 20
---
## Lookup rules
@@ -23,7 +18,7 @@ Layout
: Can be set in front matter.
Output Format
: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`), but look for less specific templates.
: See [configure output formats](/configuration/output-formats/). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`), but look for less specific templates.
Note that if the output format's Media Type has more than one suffix defined, only the first is considered.
@@ -36,9 +31,8 @@ Type
Section
: Is relevant for `section`, `taxonomy` and `term` types.
{{% note %}}
Templates can live in either the project's or the themes' `layout` directories, 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 %}}
> [!note]
> Templates can live in either the project's or the themes' `layout` directories, 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.
## Target a template
@@ -62,7 +56,7 @@ layouts/
But the contact page probably has a form and requires a different template. In the front matter specify `layout`:
{{< code-toggle file=content/contact.md >}}
{{< code-toggle file=content/contact.md fm=true >}}
title = 'Contact'
layout = 'contact'
{{< /code-toggle >}}
@@ -78,12 +72,12 @@ layouts/
As a content type, the word `page` is vague. Perhaps `miscellaneous` would be better. Add `type` to the front matter of each page:
{{< code-toggle file=content/about.md >}}
{{< code-toggle file=content/about.md fm=true >}}
title = 'About'
type = 'miscellaneous'
{{< /code-toggle >}}
{{< code-toggle file=content/contact.md >}}
{{< code-toggle file=content/contact.md fm=true >}}
title = 'Contact'
type = 'miscellaneous'
layout = 'contact'

32
docs/content/en/templates/menu.md
View File

@@ -1,15 +1,9 @@
---
title: Menus
title: Menu templates
description: Create templates to render one or more menus.
categories: [templates]
categories: []
keywords: []
menu:
docs:
identifier: templates-menu
parent: templates
weight: 180
weight: 180
toc: true
weight: 150
aliases: [/templates/menus/,/templates/menu-templates/]
---
@@ -29,7 +23,7 @@ The example below handles every combination.
This partial template recursively "walks" a menu structure, rendering a localized, accessible nested list.
{{< code file=layouts/partials/menu.html copy=true >}}
```go-html-template {file="layouts/partials/menu.html" copy=true}
{{- $page := .page }}
{{- $menuID := .menuID }}
@@ -72,14 +66,14 @@ This partial template recursively "walks" a menu structure, rendering a localize
</li>
{{- end }}
{{- end }}
{{< /code >}}
```
Call the partial above, passing a menu ID and the current page in context.
{{< code file=layouts/_default/single.html >}}
```go-html-template {file="layouts/_default/single.html"}
{{ partial "menu.html" (dict "menuID" "main" "page" .) }}
{{ partial "menu.html" (dict "menuID" "footer" "page" .) }}
{{< /code >}}
```
## Page references
@@ -87,7 +81,7 @@ Regardless of how you [define menu entries], an entry associated with a page has
This simplistic example renders a page parameter named `version` next to each entry's `name`. Code defensively using `with` or `if` to handle entries where (a) the entry points to an external resource, or (b) the `version` parameter is not defined.
{{< code file=layouts/_default/single.html >}}
```go-html-template {file="layouts/_default/single.html"}
{{- range site.Menus.main }}
<a href="{{ .URL }}">
{{ .Name }}
@@ -98,7 +92,7 @@ This simplistic example renders a page parameter named `version` next to each en
{{- end }}
</a>
{{- end }}
{{< /code >}}
```
## Menu entry parameters
@@ -109,13 +103,13 @@ When you define menu entries [in site configuration] or [in front matter], you c
This simplistic example renders a `class` attribute for each anchor element. Code defensively using `with` or `if` to handle entries where `params.class` is not defined.
{{< code file=layouts/partials/menu.html >}}
```go-html-template {file="layouts/partials/menu.html"}
{{- range site.Menus.main }}
<a {{ with .Params.class -}} class="{{ . }}" {{ end -}} href="{{ .URL }}">
{{ .Name }}
</a>
{{- end }}
{{< /code >}}
```
## Localize
@@ -127,7 +121,7 @@ Hugo provides two methods to localize your menu entries. See [multilingual].
[in front matter]: /content-management/menus/#define-in-front-matter
[in site configuration]: /content-management/menus/#define-in-site-configuration
[localize the menu entries]: /content-management/multilingual/#menus
[menu entry defined in front matter]: /content-management/menus/#example-front-matter
[menu entry defined in site configuration]: /content-management/menus/#example-site-configuration
[menu entry defined in front matter]: /content-management/menus/#example
[menu entry defined in site configuration]: /configuration/menus
[menu methods]: /methods/menu/
[multilingual]: /content-management/multilingual/#menus

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

@@ -1,241 +0,0 @@
---
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: []
menu:
docs:
parent: templates
weight: 210
weight: 210
toc: true
aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/]
---
This page describes how to properly configure your site with the media types and output formats, as well as where to create your templates for your custom outputs.
## Media types
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:
{{< datatable "config" "mediaTypes" "_key" "suffixes" >}}
Notes:
- It is possible to add custom media types or change the defaults; e.g., if you want to change the suffix for `text/html` to `asp`.
- `Suffixes` are the values that will be used for URLs and file names for that media type in Hugo.
- The `Type` is the identifier that must be used when defining new/custom `Output Formats` (see below).
- The full set of media types will be registered in Hugo's built-in development server to make sure they are recognized by the browser.
To add or modify a media type, define it in a `mediaTypes` section in your [site configuration], either for all sites or for a given language.
{{< code-toggle file=hugo >}}
[mediaTypes]
[mediaTypes."text/enriched"]
suffixes = ["enr"]
[mediaTypes."text/html"]
suffixes = ["asp"]
{{</ code-toggle >}}
The above example adds one new media type, `text/enriched`, and changes the suffix for the built-in `text/html` media type.
These media types are configured for your output formats. If you want to redefine one of Hugo's default output formats, you also need to redefine the media type. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`:
{{< code-toggle file=hugo >}}
[mediaTypes]
[mediaTypes."text/html"]
suffixes = ["htm"]
[outputFormats]
[outputFormats.html]
mediaType = "text/html"
{{</ code-toggle >}}
{{% note %}}
For the above to work, you also need to add an `outputs` definition in your site configuration.
{{% /note %}}
## Output format definitions
Given a media type and some additional configuration, you get an **Output Format**.
This is the full set of Hugo's built-in output formats:
{{< datatable "config" "outputFormats" "_key" "baseName" "isHTML" "isPlainText" "mediaType" "noUgly" "path" "permalinkable" "protocol" "rel" >}}
- A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined as long as they resolve to a unique path on the file system. In the above table, the best example of this is `amp` vs. `html`. `amp` has the value `amp` for `path` so it doesn't overwrite the `html` version; e.g. we can now have both `/index.html` and `/amp/index.html`.
- 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.
{{< code-toggle file=hugo >}}
[outputFormats.MyEnrichedFormat]
mediaType = "text/enriched"
baseName = "myindex"
isPlainText = true
protocol = "bep://"
{{</ code-toggle >}}
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
Use these parameters when configuring an output format:
baseName
: (`string`) The base name of the published file. Default is `index`.
isHTML
: (`bool`) Whether to classify the output format as HTML. Hugo uses this value to determine when to create alias redirects, when to inject the LiveReload script, etc. Default is `false`.
isPlainText
: (`bool`) Whether to parse templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`.
[html/template]: https://pkg.go.dev/html/template
[text/template]: https://pkg.go.dev/text/template
mediaType
: (`string`) The [media type] of the published file. This must match a defined media type, either [built-in](#media-types) or custom.
[media type]: https://en.wikipedia.org/wiki/Media_type
notAlternative
: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`] method on a `Page` object. Default is `false`.
[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
noUgly
: (`bool`) Whether to disable ugly URLs for this output format when `uglyURLs` is `true` in your site configuration. Default is `false`.
path
: (`string`) The path to the directory containing the published files, relative to the root of the publish directory.
permalinkable
: (`bool`) If `true`, the [`Permalink`] and [`RelPermalink`] methods on a `Page` object return the rendering output format rather than main output format ([see below](#link-to-output-formats)). Enabled by default for the `html` and `amp` output formats. Default is `false`.
[`Permalink`]: /methods/page/permalink/
[`RelPermalink`]: /methods/page/relpermalink/
protocol
: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the `baseURL` parameter in your site configuration, typically `https://`.
rel
: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`.
root
: (`bool`) Whether to publish files to the root of the publish directory. Default is `false`.
ugly
: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your site configuration. Default is `false`.
weight
: (`int`) When set to a non-zero value, Hugo uses the `weight` as the first criteria when sorting output formats, falling back to the name of the output format. Lighter items float to the top, while heavier items sink to the bottom. Hugo renders output formats sequentially based on the sort order.
## Output formats for pages
A `Page` in Hugo can be rendered to multiple _output formats_ on the file
system.
### Default output formats
Every `Page` has a [`Kind`] attribute, and the default Output
Formats are set based on that.
{{< code-toggle config=outputs />}}
### Customizing output formats
This can be changed by defining an `outputs` list of output formats in either
the `Page` front matter or in the site configuration (either for all sites or
per language).
Example from site configuration file:
{{< code-toggle file=hugo >}}
[outputs]
home = ["html", "amp", "rss"]
page = ["html"]
{{</ code-toggle >}}
Note that in the examples above, the output formats for `section`,
`taxonomy` and `term` will stay at their default value `['html','rss']`.
- The `outputs` definition is per page [`Kind`].
- The names (e.g. `html`, `amp`) must match the `name` of a defined output format, and can be overridden per page in front matter.
The following is an example of front matter in a content file that defines output formats for the rendered `Page`:
{{< code-toggle file=content/example.md fm=true >}}
title: Example
outputs:
- html
- amp
- json
{{< /code-toggle >}}
## List output formats
Each `Page` object has both an [`OutputFormats`] method (all formats, including the current) and an [`AlternativeOutputFormats`] method, the latter of which is useful for creating a `link rel` list in your site's `<head>`:
[`OutputFormats`]: /methods/page/outputformats
[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats
```go-html-template
{{ range .AlternativeOutputFormats -}}
<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
{{ end }}
```
## Link to output formats
The [`Permalink`] and [`RelPermalink`] methods on a `Page` object return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template from which they are called.
[`Permalink`]: /methods/page/permalink
[`RelPermalink`]: /methods/page/relpermalink
From `single.json.json`:
```go-html-template
{{ .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.
This is the same template file as above with the `json` output format's `permalinkable` parameter set to `true`:
```go-html-template
{{ .RelPermalink }} → /that-page/index.json
{{ with .OutputFormats.Get "html" }}
{{ .RelPermalink }} → /that-page/
{{ end }}
```
## Template lookup order
Each output format requires a template conforming to the [template lookup order].
For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name:
[template lookup order]: /templates/lookup-order/
```text
[page kind].[output format].[suffix]
```
For example, for section pages:
Output format|Template path
:--|:--
`html`|`layouts/_default/section.html.html`
`json`|`layouts/_default/section.json.json`
`rss`|`layouts/_default/section.rss.xml`
[site configuration]: /getting-started/configuration/
[`kind`]: /methods/page/kind/

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

@@ -1,14 +1,9 @@
---
title: Pagination
description: Split a list page into two or more subsets.
categories: [templates]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 190
weight: 190
toc: true
weight: 160
aliases: [/extras/pagination,/doc/pagination/]
---
@@ -20,9 +15,8 @@ Displaying a large page collection on a list page is not user-friendly:
Improve usability by paginating `home`, `section`, `taxonomy`, and `term` pages.
{{% note %}}
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 %}}
> [!note]
> 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.
## Terminology
@@ -40,43 +34,7 @@ paginator
## Configuration
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 >}}
See [configure pagination](/configuration/pagination).
## Methods
@@ -93,9 +51,6 @@ The `Paginate` method is more flexible, allowing you to:
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:
@@ -137,22 +92,17 @@ In the example above, we:
## Caching
{{% note %}}
The most common templating mistake related to pagination is invoking pagination more than once for a given list page.
{{% /note %}}
> [!note]
> The most common templating mistake related to pagination is invoking pagination more than once for a given list page.
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") }}
@@ -167,8 +117,6 @@ Use pagination with any of the [grouping methods]. For example:
{{ 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:
@@ -189,18 +137,14 @@ The `terse` format has fewer controls and page slots, consuming less space when
{{ 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.html" . }}`
[`partial`]: /functions/partials/include/
[source code]: {{% eturl pagination %}}
{{% /note %}}
> [!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.html" . }}`
Create custom navigation components using any of the `Pager` methods:
{{< list-pages-in-section path=/methods/pager >}}
{{% list-pages-in-section path=/methods/pager %}}
## Structure
@@ -288,3 +232,10 @@ public/
│ └── index.html
└── index.html
```
[`Paginate`]: /methods/page/paginate/
[`Paginator`]: /methods/page/paginator/
[`partial`]: /functions/partials/include/
[grouping methods]: /quick-reference/page-collections/#group
[grouping methods]: /quick-reference/page-collections/#group
[source code]: {{% eturl pagination %}}

40
docs/content/en/templates/partial.md
View File

@@ -1,14 +1,9 @@
---
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]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 110
weight: 110
toc: true
weight: 100
aliases: [/templates/partials/,/layout/chrome/]
---
@@ -39,13 +34,11 @@ All partials are called within your templates using the following pattern:
{{ partial "<PATH>/<PARTIAL>.html" . }}
```
{{% 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/#context).
{{% /note %}}
> [!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/#context).
{{% note %}}
`<PARTIAL>` including `baseof` is reserved. ([#5373](https://github.com/gohugoio/hugo/issues/5373))
{{% /note %}}
> [!note]
> Do not include the word "baseof" when naming partial templates. The word "baseof" is reserved for base templates.
As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory:
@@ -99,9 +92,8 @@ In addition to outputting markup, partials can be used to return a value of any
{{ end }}
```
{{% note %}}
Only one `return` statement is allowed per partial file.
{{% /note %}}
> [!note]
> Only one `return` statement is allowed per partial file.
## Inline partials
@@ -126,7 +118,7 @@ The `partialCached` template function provides significant performance gains for
The following `header.html` partial template is used for [spf13.com](https://spf13.com/):
{{< code file=layouts/partials/header.html >}}
```go-html-template {file="layouts/partials/header.html"}
<!DOCTYPE html>
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<head>
@@ -141,17 +133,16 @@ The following `header.html` partial template is used for [spf13.com](https://spf
{{ partial "head_includes.html" . }}
</head>
{{< /code >}}
```
{{% note %}}
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 %}}
> [!note]
> 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.
### `footer.html`
The following `footer.html` partial template is used for [spf13.com](https://spf13.com/):
{{< code file=layouts/partials/footer.html >}}
```go-html-template {file="layouts/partials/footer.html"}
<footer>
<div>
<p>
@@ -161,10 +152,7 @@ The following `footer.html` partial template is used for [spf13.com](https://spf
</p>
</div>
</footer>
{{< /code >}}
```
[context]: /templates/introduction/
[customize]: /hugo-modules/theme-components/
[lookup order]: /templates/lookup-order/
[partialcached]: /functions/partials/includecached/
[themes]: /themes/

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

@@ -2,13 +2,9 @@
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]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 170
weight: 170
weight: 180
aliases: [/extras/robots-txt/]
---
@@ -20,8 +16,6 @@ enableRobotsTXT = true
By default, Hugo generates robots.txt using an [embedded template].
[embedded template]: {{% eturl robots %}}
```text
User-agent: *
```
@@ -37,24 +31,23 @@ You may overwrite the internal template with a custom template. Hugo selects the
## robots.txt template example
{{< code file=layouts/robots.txt >}}
```text {file="layouts/robots.txt"}
User-agent: *
{{ range .Pages }}
Disallow: {{ .RelPermalink }}
{{ end }}
{{< /code >}}
```
This template creates a robots.txt file with a `Disallow` directive for each page on the site. Search engines that honor the Robots Exclusion Protocol will not crawl any page on the site.
{{% note %}}
To create a robots.txt file without using a template:
1. Set `enableRobotsTXT` to `false` in the site configuration.
1. Create a robots.txt file in the `static` directory.
Remember that Hugo copies everything in the [`static` directory][static] to the root of `publishDir` (typically `public`) when you build your site.
> [!note]
> To create a robots.txt file without using a template:
>
> 1. Set `enableRobotsTXT` to `false` in the site configuration.
> 1. Create a robots.txt file in the `static` directory.
>
> Remember that Hugo copies everything in the [`static` directory][static] to the root of `publishDir` (typically `public`) when you build your site.
[embedded template]: {{% eturl robots %}}
[site configuration]: /configuration/
[static]: /getting-started/directory-structure/
{{% /note %}}
[site configuration]: /getting-started/configuration/

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

@@ -1,14 +1,9 @@
---
title: RSS templates
description: Use the embedded RSS template, or create your own.
categories: [templates]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 150
weight: 150
toc: true
weight: 140
---
## Configuration
@@ -52,7 +47,7 @@ email = 'jdoe@example.org'
To include a feed reference in the `head` element of your rendered pages, place this within the `head` element of your templates:
```go-html-template
{{ with .OutputFormats.Get "rss" -}}
{{ with .OutputFormats.Get "rss" }}
{{ printf `<link rel=%q type=%q href=%q title=%q>` .Rel .MediaType.Type .Permalink site.Title | safeHTML }}
{{ end }}
```
@@ -67,9 +62,6 @@ 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]: /templates/lookup-order/#rss-templates
For example, to use different templates for home, section, taxonomy, and term pages:
```text
@@ -82,3 +74,6 @@ layouts/
```
RSS templates receive the `.Page` and `.Site` objects in context.
[embedded RSS template]: {{% eturl rss %}}
[template lookup order]: /templates/lookup-order/#rss-templates

13
docs/content/en/templates/section.md
View File

@@ -1,14 +1,9 @@
---
title: Section templates
description: Create a section template to list its members.
categories: [templates]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 80
weight: 80
toc: true
weight: 70
aliases: [/templates/sections/,/templates/section-templates/]
---
@@ -22,7 +17,7 @@ See [Template Lookup](/templates/lookup-order/).
## Example: creating a default section template
{{< code file=layouts/_default/section.html >}}
```go-html-template {file="layouts/_default/section.html"}
{{ define "main" }}
<main>
{{ .Content }}
@@ -37,7 +32,7 @@ See [Template Lookup](/templates/lookup-order/).
{{ template "_internal/pagination.html" . }}
</main>
{{ end }}
{{< /code >}}
```
### Example: using `.Site.GetPage`

209
docs/content/en/templates/shortcode.md
View File

@@ -1,23 +1,14 @@
---
title: Shortcode templates
description: Create custom shortcodes to simplify and standardize content creation.
categories: [templates]
description: Create custom shortcodes to simplify and standardize content creation.
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 130
weight: 130
weight: 120
aliases: [/templates/shortcode-templates/]
toc: true
---
{{% note %}}
Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates.
[shortcodes]: /content-management/shortcodes/
[content management]: /content-management/shortcodes/
{{% /note %}}
> [!note]
> Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates.
## Introduction
@@ -31,8 +22,6 @@ Hugo provides [embedded shortcodes] for many common tasks, but you'll likely nee
- Tables
- And many other custom elements
[embedded shortcodes]: /shortcodes/
## Directory structure
Create shortcode templates within the `layouts/shortcodes` directory, either at its root or organized into subdirectories.
@@ -81,7 +70,7 @@ foo|json|en|`layouts/shortcodes/foo.json.en.json`
Use these methods in your shortcode templates. Refer to each methods's documentation for details and examples.
{{< list-pages-in-section path=/methods/shortcode >}}
{{% list-pages-in-section path=/methods/shortcode %}}
## Examples
@@ -91,20 +80,18 @@ These examples range in complexity from simple to moderately advanced, with some
Create a shortcode to insert the current year:
{{< code file=layouts/shortcodes/year.html >}}
```go-html-template {file="layouts/shortcodes/year.html"}
{{- now.Format "2006" -}}
{{< /code >}}
```
Then call the shortcode from within your markup:
{{< code file=content/example.md >}}
```text {file="content/example.md"}
This is {{</* year */>}}, and look at how far we've come.
{{< /code >}}
```
This shortcode can be used inline or as a block on its own line. If a shortcode might be used inline, remove the surrounding [whitespace] by using [template action](g) delimiters with hyphens.
[whitespace]: /templates/introduction/#whitespace
### Insert image
This example assumes the following content structure, where `content/example/index.md` is a [page bundle](g) containing one or more [page resources](g).
@@ -119,19 +106,19 @@ content/
Create a shortcode to capture an image as a page resource, resize it to the given width, convert it to the WebP format, and add an `alt` attribute:
{{< code file=layouts/shortcodes/image.html >}}
```go-html-template {file="layouts/shortcodes/image.html"}
{{- with .Page.Resources.Get (.Get "path") }}
{{- with .Process (printf "resize %dx wepb" ($.Get "width")) }}
{{- with .Process (printf "resize %dx wepb" ($.Get "width")) -}}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ $.Get "alt" }}">
{{- end }}
{{- end -}}
{{< /code >}}
```
Then call the shortcode from within your markup:
{{< code file=content/example/index.md >}}
```text {file="content/example/index.md"}
{{</* image path=a.jpg width=300 alt="A white kitten" */>}}
{{< /code >}}
```
The example above uses:
@@ -139,47 +126,38 @@ The example above uses:
- The [`Get`] method to retrieve arguments by name
- The `$` to access the template context
[`get`]: /methods/shortcode/get/
[`with`]: /functions/go-template/with/
{{% note %}}
Make sure that you thoroughly understand the concept of context. The most common templating errors made by new users relate to context.
Read more about context in the [introduction to templating].
[introduction to templating]: /templates/introduction/
{{% /note %}}
> [!note]
> Make sure that you thoroughly understand the concept of context. The most common templating errors made by new users relate to context.
>
> Read more about context in the [introduction to templating].
### Insert image with error handling
The previous example, while functional, silently fails if the image is missing, and does not gracefully exit if a required argument is missing. We'll add error handling to address these issues:
{{< code file=layouts/shortcodes/image.html >}}
{{ with .Get "path" }}
```go-html-template {file="layouts/shortcodes/image.html"}
{{- with .Get "path" }}
{{- with $r := $.Page.Resources.Get ($.Get "path") }}
{{- with $.Get "width" }}
{{- with $r.Process (printf "resize %dx wepb" ($.Get "width" )) }}
{{- $alt := or ($.Get "alt") "" }}
{{- $alt := or ($.Get "alt") "" -}}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ $alt }}">
{{- end }}
{{- else }}
{{- errorf "The %q shortcode requires a 'width' argument: see %s" $.Name $.Position }}
{{- end }}
{{- else }}
{{ warnf "The %q shortcode was unable to find %s: see %s" $.Name ($.Get "path") $.Position }}
{{- warnf "The %q shortcode was unable to find %s: see %s" $.Name ($.Get "path") $.Position }}
{{- end }}
{{- else }}
{{ errorf "The %q shortcode requires a 'path' argument: see %s" .Name .Position }}
{{- errorf "The %q shortcode requires a 'path' argument: see %s" .Name .Position }}
{{- end -}}
{{< /code >}}
```
This template throws an error and gracefully fails the build if the author neglected to provide a `path` or `width` argument, and it emits a warning if it cannot find the image at the specified path. If the author does not provide an `alt` argument, the `alt` attribute is set to an empty string.
The [`Name`] and [`Position`] methods provide helpful context for errors and warnings. For example, a missing `width` argument causes the shortcode to throw this error:
[`name`]: /methods/shortcode/name/
[`position`]: /methods/shortcode/position/
```text
ERROR The "image" shortcode requires a 'width' argument: see "/home/user/project/content/example/index.md:7:1"
```
@@ -188,167 +166,146 @@ ERROR The "image" shortcode requires a 'width' argument: see "/home/user/project
Shortcode arguments can be [named or positional]. We used named arguments previously; let's explore positional arguments. Here's the named argument version of our example:
[named or positional]: /content-management/shortcodes/#arguments
{{< code file=content/example/index.md >}}
```text {file="content/example/index.md"}
{{</* image path=a.jpg width=300 alt="A white kitten" */>}}
{{< /code >}}
```
Here's how to call it with positional arguments:
{{< code file=content/example/index.md >}}
```text {file="content/example/index.md"}
{{</* image a.jpg 300 "A white kitten" */>}}
{{< /code >}}
```
Using the `Get` method with zero-indexed keys, we'll initialize variables with descriptive names in our template:
{{< code file=layouts/shortcodes/image.html >}}
{{- $path := .Get 0 }}
{{- $width := .Get 1 }}
{{- $alt := .Get 2 }}
{{< /code >}}
```go-html-template {file="layouts/shortcodes/image.html"}
{{ $path := .Get 0 }}
{{ $width := .Get 1 }}
{{ $alt := .Get 2 }}
```
{{% note %}}
Positional arguments work well for frequently used shortcodes with one or two arguments. Since you'll use them often, the argument order will be easy to remember. For less frequently used shortcodes, or those with more than two arguments, named arguments improve readability and reduce the chance of errors.
{{% /note %}}
> [!note]
> Positional arguments work well for frequently used shortcodes with one or two arguments. Since you'll use them often, the argument order will be easy to remember. For less frequently used shortcodes, or those with more than two arguments, named arguments improve readability and reduce the chance of errors.
### Named and positional arguments
You can create a shortcode that will accept both named and positional arguments, but not at the same time. Use the [`IsNamedParams`] method to determine whether the shortcode call used named or positional arguments:
{{< code file=layouts/shortcodes/image.html >}}
{{- $path := cond (.IsNamedParams) (.Get "path") (.Get 0) }}
{{- $width := cond (.IsNamedParams) (.Get "width") (.Get 1) }}
{{- $alt := cond (.IsNamedParams) (.Get "alt") (.Get 2) }}
{{< /code >}}
```go-html-template {file="layouts/shortcodes/image.html"}
{{ $path := cond (.IsNamedParams) (.Get "path") (.Get 0) }}
{{ $width := cond (.IsNamedParams) (.Get "width") (.Get 1) }}
{{ $alt := cond (.IsNamedParams) (.Get "alt") (.Get 2) }}
```
This example uses the `cond` alias for the [`compare.Conditional`] function to get the argument by name if `IsNamedParams` returns `true`, otherwise get the argument by position.
[`compare.Conditional`]: /functions/compare/conditional/
[`IsNamedParams`]: /methods/shortcode/isnamedparams/
### Argument collection
Use the [`Params`] method to access the arguments as a collection.
[`Params`]: /methods/shortcode/params/
When using named arguments, the `Params` method returns a map:
{{< code file=content/example/index.md >}}
```text {file="content/example/index.md"}
{{</* image path=a.jpg width=300 alt="A white kitten" */>}}
{{< /code >}}
```
{{< code file=layouts/shortcodes/image.html >}}
{{- .Params.path }} → a.jpg
{{- .Params.width }} → 300
{{- .Params.alt }} → A white kitten
{{< /code >}}
```go-html-template {file="layouts/shortcodes/image.html"}
{{ .Params.path }} → a.jpg
{{ .Params.width }} → 300
{{ .Params.alt }} → A white kitten
```
When using positional arguments, the `Params` method returns a slice:
{{< code file=content/example/index.md >}}
```text {file="content/example/index.md"}
{{</* image a.jpg 300 "A white kitten" */>}}
{{< /code >}}
```
{{< code file=layouts/shortcodes/image.html >}}
{{- index .Params 0 }} → a.jpg
{{- index .Params 1 }} → 300
{{- index .Params 1 }} → A white kitten
{{< /code >}}
```go-html-template {file="layouts/shortcodes/image.html"}
{{ index .Params 0 }} → a.jpg
{{ index .Params 1 }} → 300
{{ index .Params 1 }} → A white kitten
```
Combine the `Params` method with the [`collections.IsSet`] function to determine if a parameter is set, even if its value is falsy.
[`collections.IsSet`]: /functions/collections/isset/
### Inner content
Extract the content enclosed within shortcode tags using the [`Inner`] method. This example demonstrates how to pass both content and a title to a shortcode. The shortcode then generates a `div` element containing an `h2` element (displaying the title) and the provided content.
Extract the content enclosed within shortcode tags using the [`Inner`] method. This example demonstrates how to pass both content and a title to a shortcode. The shortcode then generates a `div` element containing an `h2` element (displaying the title) and the provided content.
[`Inner`]: /methods/shortcode/inner/
{{< code file=content/example.md >}}
```text {file="content/example.md"}
{{</* contrived title="A Contrived Example" */>}}
This is a **bold** word, and this is an _emphasized_ word.
{{</* /contrived */>}}
{{< /code >}}
```
{{< code file=layouts/shortcodes/contrived.html >}}
```go-html-template {file="layouts/shortcodes/contrived.html"}
<div class="contrived">
<h2>{{ .Get "title" }}</h2>
{{ .Inner | .Page.RenderString }}
</div>
{{< /code >}}
```
The preceding example called the shortcode using [standard notation], requiring us to process the inner content with the [`RenderString`] method to convert the Markdown to HTML. This conversion is unnecessary when calling a shortcode using [Markdown notation].
[`RenderString`]: /methods/page/renderstring/
[markdown notation]: /content-management/shortcodes/#markdown-notation
[standard notation]: /content-management/shortcodes/#standard-notation
### Nesting
The [`Parent`] method provides access to the parent shortcode context when the shortcode in question is called within the context of a parent shortcode. This provides an inheritance model.
[`Parent`]: /methods/shortcode/parent/
The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` argument:
{{< code file=layouts/shortcodes/gallery.html >}}
```go-html-template {file="layouts/shortcodes/gallery.html"}
<div class="{{ .Get "class" }}">
{{ .Inner }}
</div>
{{< /code >}}
```
You also have an `img` shortcode with a single named `src` argument that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`:
{{< code file=layouts/shortcodes/img.html >}}
```go-html-template {file="layouts/shortcodes/img.html"}
{{ $src := .Get "src" }}
{{ with .Parent }}
<img src="{{ $src }}" class="{{ .Get "class" }}-image">
{{ else }}
<img src="{{ $src }}">
{{ end }}
{{< /code >}}
```
You can then call your shortcode in your content as follows:
{{< code file=content/example.md >}}
```text {file="content/example.md"}
{{</* gallery class="content-gallery" */>}}
{{</* img src="/images/one.jpg" */>}}
{{</* img src="/images/two.jpg" */>}}
{{</* /gallery */>}}
{{</* img src="/images/three.jpg" */>}}
{{< /code >}}
```
This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`:
```html
<div class="content-gallery">
<img src="/images/one.jpg" class="content-gallery-image">
<img src="/images/two.jpg" class="content-gallery-image">
<img src="/images/one.jpg" class="content-gallery-image">
<img src="/images/two.jpg" class="content-gallery-image">
</div>
<img src="/images/three.jpg">
```
### Other examples
For guidance, consider examining Hugo's embedded shortcodes. The source code, available on [GitHub], can provide a useful model.
[GitHub]: https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates/shortcodes
For guidance, consider examining Hugo's embedded shortcodes. The source code, available on [GitHub], can provide a useful model.
## Detection
The [`HasShortcode`] method allows you to check if a specific shortcode has been called on a page. For example, consider a custom audio shortcode:
{{< code file=content/example.md >}}
```text {file="content/example.md"}
{{</* audio src=/audio/test.mp3 */>}}
{{< /code >}}
```
You can use the `HasShortcode` method in your base template to conditionally load CSS if the audio shortcode was used on the page:
{{< code file=layouts/_default/baseof.html >}}
```go-html-template {file="layouts/_default/baseof.html"}
<head>
...
{{ if .HasShortcode "audio" }}
@@ -356,6 +313,26 @@ You can use the `HasShortcode` method in your base template to conditionally loa
{{ end }}
...
</head>
{{< /code >}}
```
[`collections.IsSet`]: /functions/collections/isset/
[`compare.Conditional`]: /functions/compare/conditional/
[`Get`]: /methods/shortcode/get/
[`HasShortcode`]: /methods/page/hasshortcode/
[`Inner`]: /methods/shortcode/inner/
[`IsNamedParams`]: /methods/shortcode/isnamedparams/
[`Name`]: /methods/shortcode/name/
[`Params`]: /methods/shortcode/params/
[`Parent`]: /methods/shortcode/parent/
[`Position`]: /methods/shortcode/position/
[`RenderString`]: /methods/page/renderstring/
[`with`]: /functions/go-template/with/
[content management]: /content-management/shortcodes/
[embedded shortcodes]: /shortcodes/
[GitHub]: https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates/shortcodes
[introduction to templating]: /templates/introduction/
[Markdown notation]: /content-management/shortcodes/#markdown-notation
[named or positional]: /content-management/shortcodes/#arguments
[shortcodes]: /content-management/shortcodes/
[standard notation]: /content-management/shortcodes/#standard-notation
[whitespace]: /templates/introduction/#whitespace

17
docs/content/en/templates/single.md
View File

@@ -1,14 +1,9 @@
---
title: Single templates
description: Create a single template to render a single page.
categories: [templates]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 70
weight: 70
toc: true
weight: 60
aliases: [/layout/content/,/templates/single-page-templates/]
---
@@ -16,12 +11,12 @@ The single template below inherits the site's shell from the [base template].
[base template]: /templates/types/
{{< code file=layouts/_default/single.html >}}
```go-html-template {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.
@@ -29,7 +24,7 @@ Review the [template lookup order] to select a template path that provides the d
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 >}}
```go-html-template {file="layouts/_default/single.html"}
{{ define "main" }}
<section>
<h1>{{ .Title }}</h1>
@@ -53,4 +48,4 @@ The single template below inherits the site's shell from the base template, and
</aside>
</section>
{{ end }}
{{< /code >}}
```

32
docs/content/en/templates/sitemap.md
View File

@@ -1,14 +1,9 @@
---
title: Sitemap templates
description: Hugo provides built-in sitemap templates.
categories: [templates]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 140
weight: 140
toc: true
weight: 130
aliases: [/layout/sitemap/,/templates/sitemap-template/]
---
@@ -23,26 +18,9 @@ With a multilingual project, Hugo generates:
- A sitemap.xml file in the root of each site (language) using the [embedded sitemap template]
- A sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemapindex template]
[embedded sitemap template]: {{% eturl sitemap %}}
[embedded sitemapindex template]: {{% eturl sitemapindex %}}
## Configuration
These are the default sitemap configuration values. They apply to all pages unless overridden in front matter.
{{< code-toggle config=sitemap />}}
changefreq
: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See&nbsp;[details](https://www.sitemaps.org/protocol.html#changefreqdef).
disable {{< new-in 0.125.0 />}}
: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
filename
: (`string`) The name of the generated file. Default is `sitemap.xml`.
priority
: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See&nbsp;[details](https://www.sitemaps.org/protocol.html#priority).
See [configure sitemap](/configuration/sitemap).
## Override default values
@@ -78,5 +56,7 @@ You may disable sitemap generation in your site configuration:
disableKinds = ['sitemap']
{{</ code-toggle >}}
[`publishDir`]: /getting-started/configuration#publishdir
[`publishDir`]: /configuration/all/#publishdir
[embedded sitemap template]: {{% eturl sitemap %}}
[embedded sitemapindex template]: {{% eturl sitemapindex %}}
[sitemap protocol]: https://www.sitemaps.org/protocol.html

29
docs/content/en/templates/taxonomy.md
View File

@@ -1,14 +1,9 @@
---
title: Taxonomy templates
description: Create a taxonomy template to render a list of terms.
categories: [templates]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 90
weight: 90
toc: true
weight: 80
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy-templates/]
---
@@ -16,7 +11,7 @@ The [taxonomy](g) template below inherits the site's shell from the [base templa
[base template]: /templates/types/
{{< code file=layouts/_default/taxonomy.html >}}
```go-html-template {file="layouts/_default/taxonomy.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
@@ -24,7 +19,7 @@ The [taxonomy](g) template below inherits the site's shell from the [base templa
<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.
@@ -69,7 +64,7 @@ Once we have the `Taxonomy` object, we can call any of its [methods], allowing u
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 >}}
```go-html-template {file="layouts/_default/taxonomy.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
@@ -77,13 +72,13 @@ The taxonomy template below inherits the site's shell from the base template, an
<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 >}}
```go-html-template {file="layouts/_default/taxonomy.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
@@ -91,7 +86,7 @@ The taxonomy template below inherits the site's shell from the base template, an
<h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
{{ end }}
{{ end }}
{{< /code >}}
```
## Include content links
@@ -102,7 +97,7 @@ The [`Alphabetical`] and [`ByCount`] methods used in the previous examples retur
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 >}}
```go-html-template {file="layouts/_default/taxonomy.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
@@ -115,7 +110,7 @@ The taxonomy template below inherits the site's shell from the base template, an
</ul>
{{ end }}
{{ end }}
{{< /code >}}
```
## Display metadata
@@ -150,7 +145,7 @@ affiliation = "University of Chicago"
Then create a taxonomy template specific to the "authors" taxonomy:
{{< code file=layouts/authors/taxonomy.html >}}
```go-html-template {file="layouts/authors/taxonomy.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
@@ -164,6 +159,6 @@ Then create a taxonomy template specific to the "authors" taxonomy:
{{ end }}
{{ end }}
{{ end }}
{{< /code >}}
```
In the example above we list each author including their affiliation and portrait.

17
docs/content/en/templates/term.md
View File

@@ -1,21 +1,16 @@
---
title: Term templates
description: Create a term template to render a list of pages associated with the current term.
categories: [templates]
categories: []
keywords: []
menu:
docs:
parent: templates
weight: 100
weight: 100
toc: true
weight: 90
---
The [term](g) template below inherits the site's shell from the [base template], and renders a list of pages associated with the current term.
[base template]: /templates/types/
{{< code file=layouts/_default/term.html >}}
```go-html-template {file="layouts/_default/term.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
@@ -23,7 +18,7 @@ The [term](g) template below inherits the site's shell from the [base template],
<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.
@@ -93,7 +88,7 @@ affiliation = "University of Chicago"
Then create a term template specific to the "authors" taxonomy:
{{< code file=layouts/authors/term.html >}}
```go-html-template {file="layouts/authors/term.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
<p>Affiliation: {{ .Params.affiliation }}</p>
@@ -107,6 +102,6 @@ Then create a term template specific to the "authors" taxonomy:
<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.

93
docs/content/en/templates/types/index.md → docs/content/en/templates/types.md
View File

@@ -1,20 +1,12 @@
---
title: Template types
linkTitle: Template types
description: Create templates of different types to render your content, resources, and data.
categories: [templates]
categories: []
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.
@@ -45,11 +37,8 @@ layouts/
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.
{{% /note %}}
> [!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.
The purpose of each template type is described below.
@@ -59,10 +48,7 @@ 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 >}}
```go-html-template {file="layouts/_default/baseof.html"}
<!DOCTYPE html>
<html lang="{{ or site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
<head>
@@ -80,24 +66,24 @@ For example, the base template below calls the [partial] function to include par
</footer>
</body>
</html>
{{< /code >}}
```
Learn more about [base templates](/templates/base/).
## Home
A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages.
A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages.
{{< code file=layouts/_default/home.html >}}
```go-html-template {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" %}}
{{% include "/_common/filter-sort-group.md" %}}
Learn more about [home page templates](/templates/home/).
@@ -107,12 +93,12 @@ 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 >}}
```go-html-template {file="layouts/_default/single.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}
{{< /code >}}
```
Learn more about [single templates](/templates/single/).
@@ -122,7 +108,7 @@ 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 >}}
```go-html-template {file="layouts/_default/section.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
@@ -130,9 +116,9 @@ For example, the section template below inherits the site's shell from the base
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
```
{{% include "templates/_common/filter-sort-group.md" %}}
{{% include "/_common/filter-sort-group.md" %}}
Learn more about [section templates](/templates/section/).
@@ -142,7 +128,7 @@ A taxonomy template renders a list of terms in a [taxonomy](g).
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 >}}
```go-html-template {file="layouts/_default/taxonomy.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
@@ -150,9 +136,9 @@ For example, the taxonomy template below inherits the site's shell from the base
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
```
{{% include "templates/_common/filter-sort-group.md" %}}
{{% include "/_common/filter-sort-group.md" %}}
Learn more about [taxonomy templates](/templates/taxonomy/).
@@ -162,7 +148,7 @@ A term template renders a list of pages associated with a [term](g).
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 >}}
```go-html-template {file="layouts/_default/term.html"}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
@@ -170,9 +156,9 @@ For example, the term template below inherits the site's shell from the base tem
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
```
{{% include "templates/_common/filter-sort-group.md" %}}
{{% include "/_common/filter-sort-group.md" %}}
Learn more about [term templates](/templates/term/).
@@ -180,17 +166,14 @@ Learn more about [term templates](/templates/term/).
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 %}}
> [!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].
For example, the partial template below renders copyright information.
{{< code file=layouts/partials/footer.html >}}
```go-html-template {file="layouts/partials/footer.html"}
<p>Copyright {{ now.Year }}. All rights reserved.</p>
{{< /code >}}
```
Learn more about [partial templates](/templates/partial/).
@@ -201,11 +184,9 @@ A content view template is similar to a partial template, invoked by calling the
- 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 >}}
```go-html-template {file="layouts/_default/home.html"}
{{ define "main" }}
{{ .Content }}
<ul>
@@ -214,14 +195,14 @@ For example, the home template below inherits the site's shell from the base tem
{{ end }}
</ul>
{{ end }}
{{< /code >}}
```
{{< code file=layouts/articles/card.html >}}
```go-html-template {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/).
@@ -231,7 +212,7 @@ 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 >}}
```go-html-template {file="layouts/_default/_markup/render-link.html"}
{{- $u := urls.Parse .Destination -}}
<a href="{{ .Destination | safeURL }}"
{{- with .Title }} title="{{ . }}"{{ end -}}
@@ -240,7 +221,7 @@ For example, the render hook template below adds a `rel` attribute to external l
{{- with .Text }}{{ . }}{{ end -}}
</a>
{{- /* chomp trailing newline */ -}}
{{< /code >}}
```
Learn more about [render hook templates](/render-hooks/).
@@ -250,17 +231,17 @@ A shortcode template is used to render a component of your site. Unlike partial
For example, the shortcode template below renders an audio element from a [global resource](g).
{{< code file=layouts/shortcodes/audio.html >}}
```go-html-template {file="layouts/shortcodes/audio.html"}
{{ with resources.Get (.Get "src") }}
<audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
{{ end }}
{{< /code >}}
```
Then call the shortcode from within markup:
{{< code file=content/example.md >}}
```text {file="content/example.md"}
{{</* audio src=/audio/test.mp3 */>}}
{{< /code >}}
```
Learn more about [shortcode templates](/templates/shortcode/).
@@ -272,3 +253,9 @@ Use other specialized templates to create:
- [RSS feeds](/templates/rss/)
- [404 error pages](/templates/404/)
- [robots.txt files](/templates/robots/)
[`Render`]: /methods/page/render/
[block]: /functions/go-template/block/
[partial]: /functions/partials/include/
[template lookup order]: /templates/lookup-order/
[template lookup order]: /templates/lookup-order/

1
docs/content/en/templates/types/site-hierarchy.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 193 KiB