mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-30 18:22:37 +00:00
content: Update template type documentation
This commit is contained in:
Joe Mooring
@@ -32,7 +32,7 @@ To capture the "genres" `Taxonomy` object from within any template, use the [`Ta
|
||||
{{ $taxonomyObject := .Site.Taxonomies.genres }}
|
||||
```
|
||||
|
||||
To capture the "genres" `Taxonomy` object when rendering its page with a taxonomy template, use the [`Terms`] method on the page's [`Data`] object:
|
||||
To capture the "genres" `Taxonomy` object when rendering its page with a _taxonomy_ template, use the [`Terms`] method on the page's [`Data`] object:
|
||||
|
||||
```go-html-template {file="layouts/taxonomy.html"}
|
||||
{{ $taxonomyObject := .Data.Terms }}
|
||||
|
||||
@@ -92,7 +92,7 @@ weight: 20
|
||||
## Performance
|
||||
|
||||
[Caching]
|
||||
: Reduce build time and cost by rendering a partial template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
|
||||
: Reduce build time and cost by rendering a _partial_ template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
|
||||
|
||||
[Segmentation]
|
||||
: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire site once a week.
|
||||
|
||||
@@ -95,7 +95,7 @@ weight = 1
|
||||
|
||||
We've configured the `authors` index with a weight of `2` and the `genres` index with a weight of `1`. This means Hugo prioritizes shared `authors` as twice as significant as shared `genres`.
|
||||
|
||||
Then render a list of 5 related reviews with a partial template like this:
|
||||
Then render a list of 5 related reviews with a _partial_ template like this:
|
||||
|
||||
```go-html-template {file="layouts/_partials/related.html" copy=true}
|
||||
{{ with site.RegularPages.Related . | first 5 }}
|
||||
|
||||
@@ -237,7 +237,7 @@ Create the content adapter.
|
||||
|
||||
### Step 4
|
||||
|
||||
Create a page template to render each book review.
|
||||
Create a _page_ template to render each book review.
|
||||
|
||||
```go-html-template {file="layouts/books/page.html" copy=true}
|
||||
{{ define "main" }}
|
||||
|
||||
@@ -85,7 +85,7 @@ inline = [['@', '@']]
|
||||
|
||||
### Step 2
|
||||
|
||||
Create a partial template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section.
|
||||
Create a _partial_ template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section.
|
||||
|
||||
```go-html-template {file="layouts/_partials/math.html" copy=true}
|
||||
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
|
||||
@@ -106,7 +106,7 @@ The delimiters above must match the delimiters in your site configuration.
|
||||
|
||||
### Step 3
|
||||
|
||||
Conditionally call the partial template from the base template.
|
||||
Conditionally call the _partial_ template from the base template.
|
||||
|
||||
```go-html-template {file="layouts/baseof.html"}
|
||||
<head>
|
||||
@@ -118,7 +118,7 @@ Conditionally call the partial template from the base template.
|
||||
</head>
|
||||
```
|
||||
|
||||
The example above loads the partial template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration.
|
||||
The example above loads the _partial_ template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration.
|
||||
|
||||
### Step 4
|
||||
|
||||
@@ -179,7 +179,7 @@ MathJax and KaTeX are open-source JavaScript display engines. Both engines are f
|
||||
>
|
||||
>See the [inline delimiters](#inline-delimiters) section for details.
|
||||
|
||||
To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this:
|
||||
To use KaTeX instead of MathJax, replace the _partial_ template from [Step 2] with this:
|
||||
|
||||
```go-html-template {file="layouts/_partials/math.html" copy=true}
|
||||
<link
|
||||
|
||||
@@ -127,7 +127,7 @@ To create a list of links to translated content, use a template similar to the f
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The above can be put in a partial template then included in any template. It will not print anything if there are no translations for a given page.
|
||||
The above can be put in a _partial_ template then included in any template. It will not print anything if there are no translations for a given page.
|
||||
|
||||
The above also uses the [`i18n` function][i18func] described in the next section.
|
||||
|
||||
|
||||
@@ -63,7 +63,7 @@ With the file structure from the [example above](#overview):
|
||||
|
||||
1. The list page for the articles section includes all articles, regardless of directory structure; none of the subdirectories are sections.
|
||||
1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections.
|
||||
1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `RegularPagesRecursive` method instead of the `Pages` method in the section template.
|
||||
1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `RegularPagesRecursive` method instead of the `Pages` method in the _section_ template.
|
||||
1. All directories in the products section have list pages; each directory is a section.
|
||||
|
||||
## Template selection
|
||||
|
||||
@@ -20,7 +20,7 @@ Hugo's embedded shortcodes are pre-defined templates within the application. Ref
|
||||
|
||||
## Custom
|
||||
|
||||
Create custom shortcodes to simplify and standardize content creation. For example, the following shortcode template generates an audio player using a [global resource](g):
|
||||
Create custom shortcodes to simplify and standardize content creation. For example, the following _shortcode_ template generates an audio player using a [global resource](g):
|
||||
|
||||
```go-html-template {file="layouts/_shortcodes/audio.html"}
|
||||
{{ with resources.Get (.Get "src") }}
|
||||
@@ -38,11 +38,11 @@ Learn more about creating shortcodes in the [shortcode templates] section.
|
||||
|
||||
## Inline
|
||||
|
||||
An inline shortcode is a shortcode template defined within content.
|
||||
An inline shortcode is a _shortcode_ template defined within content.
|
||||
|
||||
Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection.
|
||||
|
||||
To conform with this security model, creating shortcode templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your site's configuration:
|
||||
To conform with this security model, creating _shortcode_ templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your site's configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[security]
|
||||
@@ -69,7 +69,7 @@ In the example above, the inline shortcode is executed twice: once upon definiti
|
||||
<p>Today is Thursday, January 30, 2025</p>
|
||||
```
|
||||
|
||||
Inline shortcodes process their inner content within the same context as regular shortcode templates, allowing you to use any available [shortcode method].
|
||||
Inline shortcodes process their inner content within the same context as regular _shortcode_ templates, allowing you to use any available [shortcode method].
|
||||
|
||||
> [!note]
|
||||
> You cannot [nest](#nesting) inline shortcodes.
|
||||
@@ -179,7 +179,7 @@ Hugo processes the shortcode before the page content is rendered by the Markdown
|
||||
|
||||
With standard notation, Hugo processes the shortcode separately, merging the output into the page content after Markdown rendering. This means, for instance, that Markdown headings inside a standard-notation shortcode will be excluded when invoking the `TableOfContents` method on the `Page` object.
|
||||
|
||||
By way of example, with this shortcode template:
|
||||
By way of example, with this _shortcode_ template:
|
||||
|
||||
```go-html-template {file="layouts/_shortcodes/foo.html"}
|
||||
{{ .Inner }}
|
||||
|
||||
@@ -139,7 +139,7 @@ title = "John Smith"
|
||||
affiliation = "University of Chicago"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Then create a taxonomy template specific to the "authors" taxonomy:
|
||||
Then create a _taxonomy_ template specific to the "authors" taxonomy:
|
||||
|
||||
```go-html-template {file="layouts/authors/taxonomy.html"}
|
||||
{{ define "main" }}
|
||||
@@ -159,7 +159,7 @@ Then create a taxonomy template specific to the "authors" taxonomy:
|
||||
|
||||
In the example above we list each author including their affiliation and portrait.
|
||||
|
||||
Or create a term template specific to the "authors" taxonomy:
|
||||
Or create a _term_ template specific to the "authors" taxonomy:
|
||||
|
||||
```go-html-template {file="layouts/authors/term.html"}
|
||||
{{ define "main" }}
|
||||
|
||||
@@ -70,6 +70,22 @@ Link to the [glossary] as needed and use terms consistently. Pay particular atte
|
||||
- "Markdown" (capitalized)
|
||||
- "open-source" (hyphenated adjective)
|
||||
|
||||
### Template types
|
||||
|
||||
When you refer to a template type, italicize it:
|
||||
|
||||
```text
|
||||
When creating a _taxonomy_ template, do this...
|
||||
```
|
||||
|
||||
However, if the template type is also a link, do not italicize it to avoid distracting formatting:
|
||||
|
||||
```text
|
||||
When creating a [taxonomy] template, do this...
|
||||
```
|
||||
|
||||
Do not italicize the template type in a title, heading, or front matter description.
|
||||
|
||||
### Titles and headings
|
||||
|
||||
- Use sentence-style capitalization.
|
||||
|
||||
@@ -75,7 +75,7 @@ Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` i
|
||||
|
||||
### Step 4
|
||||
|
||||
Create a partial template to process the CSS with the Tailwind CSS CLI:
|
||||
Create a _partial_ template to process the CSS with the Tailwind CSS CLI:
|
||||
|
||||
```go-html-template {file="layouts/_partials/css.html" copy=true}
|
||||
{{ with resources.Get "css/main.css" }}
|
||||
@@ -94,7 +94,7 @@ Create a partial template to process the CSS with the Tailwind CSS CLI:
|
||||
|
||||
### Step 5
|
||||
|
||||
Call the partial template from your base template, deferring template execution until after all sites and output formats have been rendered:
|
||||
Call the _partial_ template from your base template, deferring template execution until after all sites and output formats have been rendered:
|
||||
|
||||
```go-html-template {file="layouts/baseof.html" copy=true}
|
||||
<head>
|
||||
|
||||
@@ -53,9 +53,9 @@ content/
|
||||
└── _index.md <-- title is "My Home Page"
|
||||
```
|
||||
|
||||
And this code in the home template:
|
||||
And this code in the _home_ template:
|
||||
|
||||
```go-html-template
|
||||
```go-html-template {file="layouts/home.html"}
|
||||
{{ range site.Sections }}
|
||||
{{ range .Pages }}
|
||||
{{ page.Title }}
|
||||
@@ -71,7 +71,7 @@ My Home Page
|
||||
My Home Page
|
||||
```
|
||||
|
||||
In the example above, the global `page` function accesses the `Page` object passed into the home template; it does not access the `Page` object of the iterated pages.
|
||||
In the example above, the global `page` function accesses the `Page` object passed into the _home_ template; it does not access the `Page` object of the iterated pages.
|
||||
|
||||
### Be aware of caching
|
||||
|
||||
@@ -83,9 +83,9 @@ Do not use the global `page` function in:
|
||||
|
||||
Hugo caches rendered shortcodes. If you use the global `page` function within a shortcode, and the page content is rendered in two or more templates, the cached shortcode may be incorrect.
|
||||
|
||||
Consider this section template:
|
||||
Consider this _section_ template:
|
||||
|
||||
```go-html-template
|
||||
```go-html-template {file="layouts/section.html"}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ .Summary }}
|
||||
|
||||
@@ -43,18 +43,6 @@ Use with the [`template`] function:
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
> [!warning]
|
||||
> Only [template comments] are allowed outside of the `define` and `end` statements. Avoid placing any other text, including HTML comments, outside of these boundaries. Doing so will cause rendering issues, potentially resulting in a blank page. See the example below.
|
||||
|
||||
```go-html-template {file="layouts/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. -->
|
||||
```
|
||||
|
||||
{{% include "/_common/functions/go-template/text-template.md" %}}
|
||||
|
||||
[`block`]: /functions/go-template/block/
|
||||
|
||||
@@ -38,7 +38,9 @@ Within a range block:
|
||||
|
||||
## Understanding context
|
||||
|
||||
At the top of a page template, the [context](g) (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
|
||||
See the [context] section in the introduction to templating.
|
||||
|
||||
For example, at the top of a _page_ template, the [context](g) (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
|
||||
|
||||
With this contrived example:
|
||||
|
||||
@@ -217,3 +219,4 @@ Ranging over a non-positive integer executes the block zero times.
|
||||
[`break`]: /functions/go-template/break/
|
||||
[`continue`]: /functions/go-template/continue/
|
||||
[`else`]: /functions/go-template/else/
|
||||
[context]: /templates/introduction/#context
|
||||
|
||||
@@ -10,7 +10,7 @@ params:
|
||||
signatures: ['return [VALUE]']
|
||||
---
|
||||
|
||||
The `return` statement is a non-standard extension to Go's [text/template package]. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
|
||||
The `return` statement is a non-standard extension to Go's [text/template package]. Used within _partial_ templates, the `return` statement terminates template execution and returns the given value, if any.
|
||||
|
||||
The returned value may be of any data type including, but not limited to, [`bool`](g), [`float`](g), [`int`](g), [`map`](g), [`resource`](g), [`slice`](g), or [`string`](g).
|
||||
|
||||
@@ -21,7 +21,7 @@ A `return` statement without a value returns an empty string of type `template.H
|
||||
|
||||
## Example
|
||||
|
||||
By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even:
|
||||
By way of example, let's create a _partial_ template that _renders_ HTML, describing whether the given number is odd or even:
|
||||
|
||||
```go-html-template {file="layouts/_partials/odd-or-even.html"}
|
||||
{{ if math.ModBool . 2 }}
|
||||
|
||||
@@ -20,7 +20,7 @@ Use the `template` function to execute a defined template:
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The example above can be rewritten using an inline partial template:
|
||||
The example above can be rewritten using an inline _partial_ template:
|
||||
|
||||
```go-html-template
|
||||
{{ partial "inline/foo.html" (dict "answer" 42) }}
|
||||
|
||||
@@ -57,7 +57,9 @@ Initialize a variable, scoped to the current block:
|
||||
|
||||
## Understanding context
|
||||
|
||||
At the top of a page template, the [context](g) (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
|
||||
See the [context] section in the introduction to templating.
|
||||
|
||||
For example, at the top of a _page_ template, the [context](g) (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
|
||||
|
||||
With this contrived example:
|
||||
|
||||
@@ -90,3 +92,4 @@ This template will render the page title as desired:
|
||||
{{% include "/_common/functions/go-template/text-template.md" %}}
|
||||
|
||||
[`else`]: /functions/go-template/else/
|
||||
[context]: /templates/introduction/#context
|
||||
|
||||
@@ -100,7 +100,7 @@ Removes the given key.
|
||||
|
||||
## Determinate values
|
||||
|
||||
The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
|
||||
The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
|
||||
|
||||
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
|
||||
|
||||
|
||||
@@ -158,7 +158,7 @@ import * as params from "@params";
|
||||
import * as config from "@params/config";
|
||||
```
|
||||
|
||||
Setting the `Config` for a batch can be done from any template (including shortcode templates), but will only be set once (the first will win):
|
||||
Setting the `Config` for a batch can be done from any template (including _shortcode_ templates), but will only be set once (the first will win):
|
||||
|
||||
```go-html-template
|
||||
{{ with js.Batch "js/mybatch" }}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: partials.Include
|
||||
description: Executes the given partial template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output.
|
||||
description: Executes the given , optionally passing context. If the contains a return statement, returns the given value, else returns the rendered output.
|
||||
categories: []
|
||||
keywords: []
|
||||
params:
|
||||
@@ -15,7 +15,7 @@ Without a [`return`] statement, the `partial` function returns a string of type
|
||||
|
||||
[`return`]: /functions/go-template/return/
|
||||
|
||||
In this example we have three partial templates:
|
||||
In this example we have three _partial_ templates:
|
||||
|
||||
```text
|
||||
layouts/
|
||||
@@ -56,7 +56,7 @@ You can pass anything in context: a page, a page collection, a scalar value, a s
|
||||
{{ partial "render-student-info.html" $ctx }}
|
||||
```
|
||||
|
||||
Then, within the partial template:
|
||||
Then, within the _partial_ template:
|
||||
|
||||
```go-html-template
|
||||
<p>{{ .name }} is majoring in {{ .major }}.</p>
|
||||
@@ -64,7 +64,7 @@ Then, within the partial template:
|
||||
<p>See <a href="{{ .page.RelPermalink }}">details.</a></p>
|
||||
```
|
||||
|
||||
To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
|
||||
To return a value from a _partial_ template, it must contain only one `return` statement, placed at the end of the template:
|
||||
|
||||
```go-html-template
|
||||
{{ $result := "" }}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: partials.IncludeCached
|
||||
description: Executes the given template and caches the result, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output.
|
||||
description: Executes the given template and caches the result, optionally passing context. If the contains a return statement, returns the given value, else returns the rendered output.
|
||||
categories: []
|
||||
keywords: []
|
||||
params:
|
||||
@@ -38,9 +38,9 @@ Pass additional arguments, of any data type, as needed to create unique variants
|
||||
{{ partialCached "footer.html" . .Params.country .Params.province }}
|
||||
```
|
||||
|
||||
The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys.
|
||||
The variant arguments are not available to the underlying _partial_ template; they are only used to create unique cache keys.
|
||||
|
||||
To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
|
||||
To return a value from a _partial_ template, it must contain only one `return` statement, placed at the end of the template:
|
||||
|
||||
```go-html-template
|
||||
{{ $result := "" }}
|
||||
|
||||
@@ -64,7 +64,7 @@ To visually mark where a template begins and ends execution:
|
||||
|
||||
### Call stack
|
||||
|
||||
To display the chain of templates that led to the current one, create a partial template that iterates through its ancestors:
|
||||
To display the chain of templates that led to the current one, create a _partial_ template that iterates through its ancestors:
|
||||
|
||||
```go-html-template {file="layouts/_partials/template-call-stack.html" copy=true}
|
||||
{{ with templates.Current }}
|
||||
@@ -113,7 +113,7 @@ To reverse the order of the entries, chain the `Reverse` method to the `Ancestor
|
||||
|
||||
### VS Code
|
||||
|
||||
To render links that, when clicked, will open the template in Microsoft Visual Studio Code, create a partial template with anchor elements that use the `vscode` URI scheme:
|
||||
To render links that, when clicked, will open the template in Microsoft Visual Studio Code, create a _partial_ template with anchor elements that use the `vscode` URI scheme:
|
||||
|
||||
```go-html-template {file="layouts/_partials/template-open-in-vs-code.html" copy=true}
|
||||
{{ with templates.Current.Parent }}
|
||||
|
||||
@@ -14,7 +14,7 @@ aliases: [/functions/templates.defer]
|
||||
{{< new-in 0.128.0 />}}
|
||||
|
||||
> [!note]
|
||||
> This feature should only be used in the main page template, typically `layouts/baseof.html`. Using it in shortcodes, partials, or render hook templates may lead to unpredictable results. For further details, please refer to [this issue].
|
||||
> This feature should only be used in the main template, typically `layouts/baseof.html`. Using it in shortcodes, partials, or _render hook_ templates may lead to unpredictable results. For further details, please refer to [this issue].
|
||||
|
||||
[this issue]: https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391
|
||||
|
||||
|
||||
@@ -38,7 +38,7 @@ content/
|
||||
|
||||
## In a taxonomy template
|
||||
|
||||
Use these methods on the `Data` object within a taxonomy template.
|
||||
Use these methods on the `Data` object within a _taxonomy_ template.
|
||||
|
||||
Singular
|
||||
: (`string`) Returns the singular name of the taxonomy.
|
||||
@@ -68,7 +68,7 @@ Learn more about [taxonomy templates].
|
||||
|
||||
## In a term template
|
||||
|
||||
Use these methods on the `Data` object within a term template.
|
||||
Use these methods on the `Data` object within a _term_ template.
|
||||
|
||||
Singular
|
||||
: (`string`) Returns the singular name of the taxonomy.
|
||||
|
||||
@@ -9,25 +9,25 @@ params:
|
||||
signatures: [PAGE.Page]
|
||||
---
|
||||
|
||||
This is a convenience method, useful within partial templates that are called from both [shortcodes](g) and page templates.
|
||||
This is a convenience method, useful within _partial_ templates that are called from both _shortcode_ and other template types.
|
||||
|
||||
```go-html-template {file="layouts/_shortcodes/foo.html"}
|
||||
{{ partial "my-partial.html" . }}
|
||||
```
|
||||
|
||||
When the shortcode calls the partial, it passes the current [context](g) (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`.
|
||||
When the _shortcode_ template calls the _partial_ template, it passes the current [context](g) (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`.
|
||||
|
||||
```go-html-template {file="layouts/page.html"}
|
||||
{{ partial "my-partial.html" . }}
|
||||
```
|
||||
|
||||
When the page template calls the partial, it also passes the current context (the dot). But in this case, the dot _is_ the `Page` object.
|
||||
When the _page_ template calls the _partial_ template, it also passes the current context (the dot). But in this case, the dot _is_ the `Page` object.
|
||||
|
||||
```go-html-template {file="layouts/_partials/my-partial.html"}
|
||||
The page title is: {{ .Page.Title }}
|
||||
```
|
||||
|
||||
To handle both scenarios, the partial template must be able to access the `Page` object with `Page.Page`.
|
||||
To handle both scenarios, the _partial_ template must be able to access the `Page` object with `Page.Page`.
|
||||
|
||||
> [!note]
|
||||
> And yes, that means you can do `.Page.Page.Page.Page.Title` too.
|
||||
|
||||
@@ -18,7 +18,7 @@ By default, the number of elements on each pager is determined by your [site con
|
||||
>
|
||||
> The `Paginate` method is more flexible.
|
||||
|
||||
You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates].
|
||||
You can invoke pagination in [home], [section], [taxonomy], and [term] templates.
|
||||
|
||||
```go-html-template {file="layouts/section.html"}
|
||||
{{ $pages := where .Site.RegularPages "Section" "articles" }}
|
||||
@@ -40,8 +40,8 @@ In the example above, we:
|
||||
> [!note]
|
||||
> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
|
||||
|
||||
[home template]: /templates/types/#home
|
||||
[section templates]: /templates/types/#section
|
||||
[home]: /templates/types/#home
|
||||
[section]: /templates/types/#section
|
||||
[site configuration]: /configuration/pagination/
|
||||
[taxonomy templates]: /templates/types/#taxonomy
|
||||
[term templates]: /templates/types/#term
|
||||
[taxonomy]: /templates/types/#taxonomy
|
||||
[term]: /templates/types/#term
|
||||
|
||||
@@ -13,7 +13,7 @@ Pagination is the process of splitting a list page into two or more pagers, wher
|
||||
|
||||
The number of elements on each pager is determined by your [site configuration]. The default is `10`.
|
||||
|
||||
You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates]. Each of these receives a collection of regular pages in [context](g). When you invoke the `Paginator` method, it paginates the page collection received in context.
|
||||
You can invoke pagination in [home], [section], [taxonomy], and [term] templates. Each of these receives a collection of regular pages in [context](g). When you invoke the `Paginator` method, it paginates the page collection received in context.
|
||||
|
||||
```go-html-template {file="layouts/section.html"}
|
||||
{{ range .Paginator.Pages }}
|
||||
@@ -32,9 +32,9 @@ In the example above, the embedded pagination template creates navigation links
|
||||
> [!note]
|
||||
> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
|
||||
|
||||
[home template]: /templates/types/#home
|
||||
[section templates]: /templates/types/#section
|
||||
[home]: /templates/types/#home
|
||||
[section]: /templates/types/#section
|
||||
[site configuration]: /configuration/pagination/
|
||||
[taxonomy templates]: /templates/types/#taxonomy
|
||||
[term templates]: /templates/types/#term
|
||||
[taxonomy]: /templates/types/#taxonomy
|
||||
[term]: /templates/types/#term
|
||||
[`Paginate`]: /methods/page/paginate/
|
||||
|
||||
@@ -9,7 +9,7 @@ params:
|
||||
signatures: [PAGE.RenderShortcodes]
|
||||
---
|
||||
|
||||
Use this method in shortcode templates to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents.
|
||||
Use this method in _shortcode_ templates to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents.
|
||||
|
||||
For example:
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ Use the `Store` method on a `Page` object to create a [scratch pad](g) to store
|
||||
|
||||
## Determinate values
|
||||
|
||||
The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
|
||||
The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
|
||||
|
||||
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ params:
|
||||
|
||||
To support both positional and named arguments when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called.
|
||||
|
||||
With this shortcode template:
|
||||
With this _shortcode_ template:
|
||||
|
||||
```go-html-template {file="layouts/_shortcodes/myshortcode.html"}
|
||||
{{ if .IsNamedParams }}
|
||||
|
||||
@@ -47,6 +47,6 @@ Hugo renders the page to:
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top-level context passed into the template.
|
||||
> In the _shortcode_ template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top-level context passed into the template.
|
||||
|
||||
[`with`]: /functions/go-template/with/
|
||||
|
||||
@@ -34,9 +34,9 @@ content/
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
This home template:
|
||||
This _home_ template:
|
||||
|
||||
```go-html-template
|
||||
```go-html-template {file="layouts/home.html"}
|
||||
{{ with .Site.GetPage "/works/paintings" }}
|
||||
<ul>
|
||||
{{ range .Pages }}
|
||||
@@ -57,7 +57,7 @@ Is rendered to:
|
||||
|
||||
To get a regular page instead of a section page:
|
||||
|
||||
```go-html-template
|
||||
```go-html-template {file="layouts/home.html"}
|
||||
{{ with .Site.GetPage "/works/paintings/starry-night" }}
|
||||
{{ .Title }} → Starry Night
|
||||
{{ .Params.artist }} → Vincent van Gogh
|
||||
@@ -94,9 +94,9 @@ content/
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
In the home template, use the `GetPage` method on a `Site` object to render all the images in the headless [page bundle](g):
|
||||
In the _home_ template, use the `GetPage` method on a `Site` object to render all the images in the headless [page bundle](g):
|
||||
|
||||
```go-html-template
|
||||
```go-html-template {file="layouts/home.html"}
|
||||
{{ with .Site.GetPage "/headless" }}
|
||||
{{ range .Resources.ByType "image" }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
|
||||
|
||||
@@ -45,9 +45,9 @@ Template:
|
||||
|
||||
When creating a theme, instead of hardcoding section names when listing the most relevant pages on the front page, instruct site authors to set `mainSections` in their site configuration.
|
||||
|
||||
Then your home template can do something like this:
|
||||
Then your _home_ template can do something like this:
|
||||
|
||||
```go-html-template
|
||||
```go-html-template {file="layouts/home.html"}
|
||||
{{ range where .Site.RegularPages "Section" "in" .Site.MainSections }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
|
||||
@@ -79,7 +79,7 @@ When viewing the "books" page, the result is:
|
||||
</nav>
|
||||
```
|
||||
|
||||
You will typically render a menu using a partial template. As the active menu entry will be different on each page, use the [`partial`] function to call the template. Do not use the [`partialCached`] function.
|
||||
You will typically render a menu using a _partial_ template. As the active menu entry will be different on each page, use the [`partial`] function to call the template. Do not use the [`partialCached`] function.
|
||||
|
||||
The example above is simplistic. Please see the [menu templates] section for more information.
|
||||
|
||||
|
||||
@@ -100,7 +100,7 @@ Removes the given key.
|
||||
|
||||
## Determinate values
|
||||
|
||||
The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
|
||||
The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
|
||||
|
||||
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Render hooks
|
||||
description: Create render hooks to override the rendering of Markdown to HTML.
|
||||
description: Create render hook templates to override the rendering of Markdown to HTML.
|
||||
categories: []
|
||||
keywords: []
|
||||
weight: 10
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Blockquote render hooks
|
||||
linkTitle: Blockquotes
|
||||
description: Create a blockquote render hook to override the rendering of Markdown blockquotes to HTML.
|
||||
description: Create blockquote render hook templates to override the rendering of Markdown blockquotes to HTML.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
@@ -10,7 +10,7 @@ keywords: []
|
||||
|
||||
## Context
|
||||
|
||||
Blockquote render hook templates receive the following [context](g):
|
||||
Blockquote _render hook_ templates receive the following [context](g):
|
||||
|
||||
AlertType
|
||||
: (`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Code block render hooks
|
||||
linkTitle: Code blocks
|
||||
description: Create a code block render hook to override the rendering of Markdown code blocks to HTML.
|
||||
description: Create code block render hook templates to override the rendering of Markdown code blocks to HTML.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
@@ -41,7 +41,7 @@ In the example above, the _highlighting options_ are `lineNos` and `tabWidth`. H
|
||||
|
||||
## Context
|
||||
|
||||
Code block render hook templates receive the following [context](g):
|
||||
Code block _render hook_ templates receive the following [context](g):
|
||||
|
||||
Attributes
|
||||
: (`map`) The generic attributes from the info string.
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
---
|
||||
title: Heading render hooks
|
||||
linkTitle: Headings
|
||||
description: Create a heading render hook to override the rendering of Markdown headings to HTML.
|
||||
description: Create heading render hook templates to override the rendering of Markdown headings to HTML.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Heading render hook templates receive the following [context](g):
|
||||
Heading _render hook_ templates receive the following [context](g):
|
||||
|
||||
Anchor
|
||||
: (`string`) The `id` attribute of the heading element.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Image render hooks
|
||||
linkTitle: Images
|
||||
description: Create an image render to hook override the rendering of Markdown images to HTML.
|
||||
description: Create image render hook templates to override the rendering of Markdown images to HTML.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
@@ -20,7 +20,7 @@ These components are passed into the render hook [context](g) as shown below.
|
||||
|
||||
## Context
|
||||
|
||||
Image render hook templates receive the following context:
|
||||
Image _render hook_ templates receive the following context:
|
||||
|
||||
Attributes
|
||||
: (`map`) The [Markdown attributes], available if you configure your site as follows:
|
||||
|
||||
@@ -20,7 +20,7 @@ These components are passed into the render hook [context](g) as shown below.
|
||||
|
||||
## Context
|
||||
|
||||
Link render hook templates receive the following context:
|
||||
Link _render hook_ templates receive the following context:
|
||||
|
||||
Destination
|
||||
: (`string`) The link destination.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Passthrough render hooks
|
||||
linkTitle: Passthrough
|
||||
description: Create a passthrough render hook to override the rendering of text snippets captured by the Goldmark Passthrough extension.
|
||||
description: Create passthrough render hook templates to override the rendering of text snippets captured by the Goldmark Passthrough extension.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
@@ -47,7 +47,7 @@ To enable custom rendering of passthrough elements, create a passthrough render
|
||||
|
||||
## Context
|
||||
|
||||
Passthrough render hook templates receive the following [context](g):
|
||||
Passthrough _render hook_ templates receive the following [context](g):
|
||||
|
||||
Attributes
|
||||
: (`map`) The [Markdown attributes], available if you configure your site as follows:
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Table render hooks
|
||||
linkTitle: Tables
|
||||
description: Create a table render hook to override the rendering of Markdown tables to HTML.
|
||||
description: Create table render hook templates to override the rendering of Markdown tables to HTML.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
@@ -10,7 +10,7 @@ keywords: []
|
||||
|
||||
## Context
|
||||
|
||||
Table render hook templates receive the following [context](g):
|
||||
Table _render hook_ templates receive the following [context](g):
|
||||
|
||||
Attributes
|
||||
: (`map`) The [Markdown attributes], available if you configure your site as follows:
|
||||
|
||||
@@ -35,7 +35,7 @@ While HTML templates are the most common, you can create templates for any [outp
|
||||
|
||||
The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects](g) and associated [methods](g).
|
||||
|
||||
For example, a template for a single page receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
|
||||
For example, a _page_ template receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
|
||||
|
||||
### Current context
|
||||
|
||||
@@ -343,7 +343,7 @@ Use the [`partial`] or [`partialCached`] function to include one or more [partia
|
||||
{{ partialCached "css.html" . }}
|
||||
```
|
||||
|
||||
Create your partial templates in the layouts/_partials directory.
|
||||
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.
|
||||
|
||||
@@ -21,7 +21,7 @@ The example below handles every combination.
|
||||
|
||||
## Example
|
||||
|
||||
This partial template recursively "walks" a menu structure, rendering a localized, accessible nested list.
|
||||
This _partial_ template recursively "walks" a menu structure, rendering a localized, accessible nested list.
|
||||
|
||||
```go-html-template {file="layouts/_partials/menu.html" copy=true}
|
||||
{{- $page := .page }}
|
||||
|
||||
@@ -32,7 +32,7 @@ Also, see the [Example folder structure] below for a more concrete example of th
|
||||
|
||||
## Changes to template lookup order
|
||||
|
||||
We have consolidated the template lookup so it works the same across all shortcodes, render hooks, partials, and page templates. The previous setup was very hard to understand and had a massive number of variants. The new setup aims to feel natural with few surprises.
|
||||
We have consolidated the template lookup so it works the same across all [template types]. The previous setup was very hard to understand and had a massive number of variants. The new setup aims to feel natural with few surprises.
|
||||
|
||||
The identifiers used in the template weighting, in order of importance, are:
|
||||
|
||||
@@ -90,10 +90,11 @@ layouts
|
||||
└── list.html
|
||||
```
|
||||
|
||||
[Hugo v0.146.0]: https://github.com/gohugoio/hugo/releases/tag/v0.146.0
|
||||
[Page path]: https://gohugo.io/methods/page/path/
|
||||
[Page kinds]: https://gohugo.io/methods/page/kind/
|
||||
[Example folder structure]: #example-folder-structure
|
||||
|
||||
[^type]: The `type` set in front matter will effectively replace the `section` folder in [Page path] when doing lookups.
|
||||
[^internal]: The old way of doing it made it very hard/impossible to, e.g., override `_internal/disqus.html` in a theme. Now you can just create a partial with the same name.
|
||||
|
||||
[Example folder structure]: #example-folder-structure
|
||||
[Hugo v0.146.0]: https://github.com/gohugoio/hugo/releases/tag/v0.146.0
|
||||
[Page kinds]: https://gohugo.io/methods/page/kind/
|
||||
[Page path]: https://gohugo.io/methods/page/path/
|
||||
[template types]: /templates/types/
|
||||
|
||||
@@ -172,9 +172,9 @@ And this site configuration:
|
||||
path = 'page'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
And this section template:
|
||||
And this _section_ template:
|
||||
|
||||
```go-html-template
|
||||
```go-html-template {file="layouts/section.html"}
|
||||
{{ range (.Paginate .Pages).Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
|
||||
@@ -27,7 +27,7 @@ Hugo provides [embedded shortcodes] for many common tasks, but you'll likely nee
|
||||
|
||||
## Directory structure
|
||||
|
||||
Create shortcode templates within the `layouts/_shortcodes` directory, either at its root or organized into subdirectories.
|
||||
Create _shortcode_ templates within the `layouts/_shortcodes` directory, either at its root or organized into subdirectories.
|
||||
|
||||
```text
|
||||
layouts/
|
||||
@@ -53,7 +53,7 @@ When calling a shortcode in a subdirectory, specify its path relative to the `_s
|
||||
|
||||
## Lookup order
|
||||
|
||||
Hugo selects shortcode templates based on the shortcode name, the current output format, and the current language. The examples below are sorted by specificity in descending order. The least specific path is at the bottom of the list.
|
||||
Hugo selects _shortcode_ templates based on the shortcode name, the current output format, and the current language. The examples below are sorted by specificity in descending order. The least specific path is at the bottom of the list.
|
||||
|
||||
Shortcode name|Output format|Language|Template path
|
||||
:--|:--|:--|:--
|
||||
@@ -71,7 +71,7 @@ foo|json|en|`layouts/_shortcodes/foo.json.en.json`
|
||||
|
||||
## Methods
|
||||
|
||||
Use these methods in your shortcode templates. Refer to each methods's documentation for details and examples.
|
||||
Use these methods in your _shortcode_ templates. Refer to each methods's documentation for details and examples.
|
||||
|
||||
{{% list-pages-in-section path=/methods/shortcode %}}
|
||||
|
||||
|
||||
@@ -58,13 +58,24 @@ The purpose of each template type is described below.
|
||||
|
||||
## Base
|
||||
|
||||
A base template reduces duplicate code by wrapping other templates within a shell.
|
||||
A _base_ template serves as a foundational layout that other templates can build upon. It typically defines the common structural components of your HTML, such as the `html`, `head`, and `body` elements. It also often includes recurring features like headers, footers, navigation, and script inclusions that appear across multiple pages of your site. By defining these common aspects once in a _base_ template, you avoid redundancy, ensure consistency, and simplify the maintenance of your website.
|
||||
|
||||
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 calls the [`block`] function to include `home`, `page`, `section`, `taxonomy`, and `term` templates within the `main` element of each page.
|
||||
A _base_ template can be applied to these template types: [home](#home), [page](#page), [section](#section), [taxonomy](#taxonomy), [term](#term), [single](#single), [list](#list), and [all](#all). When Hugo parses any of these template types, it will apply a _base_ template if the template being parsed meets these specific criteria:
|
||||
|
||||
- It must begin with a [`define`] [action](g).
|
||||
- This `define` action can optionally be preceded by a [template comment] or whitespace.
|
||||
- The template must only contain `define` actions.
|
||||
|
||||
> [!note]
|
||||
> If the template does not satisfy all the criteria, it will be executed exactly as provided, without the application of a _base_ template.
|
||||
|
||||
When Hugo applies a _base_ template, it replaces its `block` actions with content from the corresponding `define` actions found in the template to which the base template is applied.
|
||||
|
||||
For example, the _base_ template below calls the [`partial`] function to include `head`, `header`, and `footer` elements. The `block` action acts as a placeholder, and its content will be replaced by a matching `define` action from the template to which it is applied.
|
||||
|
||||
```go-html-template {file="layouts/baseof.html"}
|
||||
<!DOCTYPE html>
|
||||
<html lang="{{ or site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
|
||||
<html lang="{{ site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
|
||||
<head>
|
||||
{{ partial "head.html" . }}
|
||||
</head>
|
||||
@@ -73,7 +84,11 @@ For example, the base template below calls the [`partial`] function to include p
|
||||
{{ partial "header.html" . }}
|
||||
</header>
|
||||
<main>
|
||||
{{ block "main" . }}{{ end }}
|
||||
{{ block "main" . }}
|
||||
This will be replaced with content from the
|
||||
corresponding "define" action found in the template
|
||||
to which this base template is applied.
|
||||
{{ end }}
|
||||
</main>
|
||||
<footer>
|
||||
{{ partial "footer.html" . }}
|
||||
@@ -82,11 +97,18 @@ For example, the base template below calls the [`partial`] function to include p
|
||||
</html>
|
||||
```
|
||||
|
||||
The `block` construct above is used to define a set of root templates that are then customized by redefining the block templates within. See [details](/functions/go-template/block/)
|
||||
```go-html-template {file="layouts/home.html"}
|
||||
{{ define "main" }}
|
||||
This will replace the content of the "block" action
|
||||
found in the base template.
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Home
|
||||
|
||||
A home template renders your site's home page. For example, the home 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_ template renders your site's home page.
|
||||
|
||||
For example, Hugo applies a _base_ template to the _home_ template below, then renders the page content and a list of the site's regular pages.
|
||||
|
||||
```go-html-template {file="layouts/home.html"}
|
||||
{{ define "main" }}
|
||||
@@ -101,9 +123,9 @@ A home template renders your site's home page. For example, the home template be
|
||||
|
||||
## Page
|
||||
|
||||
A page template renders a regular page.
|
||||
A _page_ template renders a regular page.
|
||||
|
||||
For example, the page template below inherits the site's shell from the [base template] and renders the page title and page content.
|
||||
For example, Hugo applies a _base_ template to the _page_ template below, then renders the page title and page content.
|
||||
|
||||
```go-html-template {file="layouts/page.html"}
|
||||
{{ define "main" }}
|
||||
@@ -114,9 +136,9 @@ For example, the page template below inherits the site's shell from the [base te
|
||||
|
||||
## Section
|
||||
|
||||
A section template renders a list of pages within a section.
|
||||
A _section_ template renders a list of pages within a [section](g).
|
||||
|
||||
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.
|
||||
For example, Hugo applies a _base_ template to the _section_ template below, then renders the page title, page content, and a list of pages in the current section.
|
||||
|
||||
```go-html-template {file="layouts/section.html"}
|
||||
{{ define "main" }}
|
||||
@@ -132,9 +154,9 @@ For example, the section template below inherits the site's shell from the [base
|
||||
|
||||
## Taxonomy
|
||||
|
||||
A taxonomy template renders a list of terms in a [taxonomy](g).
|
||||
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.
|
||||
For example, Hugo applies a _base_ template to the _taxonomy_ template below, then renders the page title, page content, and a list of [terms](g) in the current taxonomy.
|
||||
|
||||
```go-html-template {file="layouts/taxonomy.html"}
|
||||
{{ define "main" }}
|
||||
@@ -148,11 +170,11 @@ For example, the taxonomy template below inherits the site's shell from the [bas
|
||||
|
||||
{{% include "/_common/filter-sort-group.md" %}}
|
||||
|
||||
Within a taxonomy template, the [`Data`] object provides these taxonomy-specific methods:
|
||||
Within a _taxonomy_ template, the [`Data`] object provides these taxonomy-specific methods:
|
||||
|
||||
- [`Singular`][taxonomy-singular]
|
||||
- [`Plural`][taxonomy-plural]
|
||||
- [`Terms`].
|
||||
- [`Terms`]
|
||||
|
||||
The `Terms` method returns a [taxonomy object](g), allowing you to call any of its methods including [`Alphabetical`] and [`ByCount`]. For example, use the `ByCount` method to render a list of terms sorted by the number of pages associated with each term:
|
||||
|
||||
@@ -168,9 +190,9 @@ The `Terms` method returns a [taxonomy object](g), allowing you to call any of i
|
||||
|
||||
## Term
|
||||
|
||||
A term template renders a list of pages associated with a [term](g).
|
||||
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.
|
||||
For example, Hugo applies a _base_ template to the _term_ template below, then renders the page title, page content, and a list of pages associated with the current term.
|
||||
|
||||
```go-html-template {file="layouts/term.html"}
|
||||
{{ define "main" }}
|
||||
@@ -184,19 +206,17 @@ For example, the term template below inherits the site's shell from the [base te
|
||||
|
||||
{{% include "/_common/filter-sort-group.md" %}}
|
||||
|
||||
Within a term template, the [`Data`] object provides these term-specific methods:
|
||||
Within a _term_ template, the [`Data`] object provides these term-specific methods:
|
||||
|
||||
- [`Singular`][term-singular]
|
||||
- [`Plural`][term-plural]
|
||||
- [`Term`].
|
||||
- [`Term`]
|
||||
|
||||
## Single
|
||||
|
||||
A single template is a fallback for [page templates](#page). If a page template does not exist, Hugo will look for a single template instead.
|
||||
A _single_ template is a fallback for a _page_ template. If a _page_ template does not exist, Hugo will look for a _single_ template instead.
|
||||
|
||||
Like a page template, a single template renders a regular page.
|
||||
|
||||
For example, the single template below inherits the site's shell from the [base template] and renders the page title and page content.
|
||||
For example, Hugo applies a _base_ template to the _single_ template below, then renders the page title and page content.
|
||||
|
||||
```go-html-template {file="layouts/single.html"}
|
||||
{{ define "main" }}
|
||||
@@ -207,9 +227,9 @@ For example, the single template below inherits the site's shell from the [base
|
||||
|
||||
## List
|
||||
|
||||
A list template is a fallback for these template types: [home](#home), [section](#section), [taxonomy](#taxonomy), and [term](#term). If one of these template types does not exist, Hugo will look for a list template instead.
|
||||
A _list_ template is a fallback for [home](#home), [section](#section), [taxonomy](#taxonomy), and [term](#term) templates. If one of these template types does not exist, Hugo will look for a _list_ template instead.
|
||||
|
||||
For example, the list template below inherits the site's shell from the [base template] and renders a list of pages:
|
||||
For example, Hugo applies a _base_ template to the _list_ template below, then renders the page title, page content, and a list of pages.
|
||||
|
||||
```go-html-template {file="layouts/list.html"}
|
||||
{{ define "main" }}
|
||||
@@ -223,9 +243,9 @@ For example, the list template below inherits the site's shell from the [base te
|
||||
|
||||
## All
|
||||
|
||||
An "all" template is a fallback for these template types: [home](#home), [page](#page), [section](#section), [taxonomy](#taxonomy), [term](#term), [single](#single), and [list](#list). If one of these template types does not exist, Hugo will look for an "all" template instead.
|
||||
An _all_ template is a fallback for [home](#home), [page](#page), [section](#section), [taxonomy](#taxonomy), [term](#term), [single](#single), and [list](#list) templates. If one of these template types does not exist, Hugo will look for an _all_ template instead.
|
||||
|
||||
For example, the contrived "all" template below inherits the site's shell from the [base template] and conditionally renders a page based on its page kind:
|
||||
For example, Hugo applies a _base_ template to the _all_ template below, then conditionally renders a page based on its page kind.
|
||||
|
||||
```go-html-template {file="layouts/all.html"}
|
||||
{{ define "main" }}
|
||||
@@ -251,24 +271,23 @@ For example, the contrived "all" template below inherits the site's shell from t
|
||||
|
||||
## Partial
|
||||
|
||||
A partial template is typically used to render a component of your site, though you may also create partial templates that return values.
|
||||
A _partial_ template is typically used to render a component of your site, though you may also create _partial_ templates that return values.
|
||||
|
||||
|
||||
For example, the partial template below renders copyright information:
|
||||
For example, the _partial_ template below renders copyright information:
|
||||
|
||||
```go-html-template {file="layouts/_partials/footer.html"}
|
||||
<p>Copyright {{ now.Year }}. All rights reserved.</p>
|
||||
```
|
||||
|
||||
Execute the partial template by calling the [`partial`] or [`partialCached`] function, optionally passing context as the second argument:
|
||||
Execute the _partial_ template by calling the [`partial`] or [`partialCached`] function, optionally passing context as the second argument:
|
||||
|
||||
```go-html-template {file="layouts/baseof.html"}
|
||||
{{ partial "footer.html" . }}
|
||||
```
|
||||
|
||||
Unlike other template types, partial template selection is based on the file name passed in the partial call. Hugo does not consider the current page kind, content type, logical path, language, or output format when searching for a matching partial template. However, Hugo _does_ apply the same name matching logic it uses for other templates. This means it tries to find the most specific match first, then progressively looks for more general versions if the specific one isn't found.
|
||||
Unlike other template types, _partial_ template selection is based on the file name passed in the `partial` or `partialCached` call. Hugo does not consider the current page kind, content type, logical path, language, or output format when searching for a matching _partial_ template. However, Hugo _does_ apply the same name matching logic it uses for other templates. This means it tries to find the most specific match first, then progressively looks for more general versions if the specific one isn't found.
|
||||
|
||||
For example, with this partial call:
|
||||
For example, with this call:
|
||||
|
||||
```go-html-template {file="layouts/baseof.html"}
|
||||
{{ partial "footer.section.de.html" . }}
|
||||
@@ -281,7 +300,7 @@ Hugo uses this lookup order to find a matching template:
|
||||
1. `layouts/_partials/footer.de.html`
|
||||
1. `layouts/_partials/footer.html`
|
||||
|
||||
Partials can also be defined inline within a template. However, it's important to note that the template namespace is global; ensuring unique names for these partials is necessary to prevent conflicts.
|
||||
A _partial_ template can also be defined inline within another template. However, it's important to note that the template namespace is global; ensuring unique names for these _partial_ templates is necessary to prevent conflicts.
|
||||
|
||||
```go-html-template
|
||||
Value: {{ partial "my-inline-partial.html" . }}
|
||||
@@ -294,12 +313,12 @@ Value: {{ partial "my-inline-partial.html" . }}
|
||||
|
||||
## Content view
|
||||
|
||||
A content view template is similar to a partial template, invoked by calling the [`Render`] method on a `Page` object. Unlike partial templates, content view templates:
|
||||
A _content view_ template is similar to a _partial_ template, invoked by calling the [`Render`] method on a `Page` object. Unlike _partial_ templates, _content view_ templates:
|
||||
|
||||
- Inherit the context of the current page
|
||||
- Can target any page kind, content type, logical path, language, or output format
|
||||
|
||||
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 "films" section of your site.
|
||||
For example, Hugo applies a _base_ template to the _home_ template below, then renders the page content and a card component for each page within the "films" section of your site.
|
||||
|
||||
```go-html-template {file="layouts/home.html"}
|
||||
{{ define "main" }}
|
||||
@@ -321,9 +340,9 @@ For example, the home template below inherits the site's shell from the [base te
|
||||
|
||||
## Render hook
|
||||
|
||||
A render hook template overrides the conversion of Markdown to HTML.
|
||||
A _render hook_ template overrides the conversion of Markdown to HTML.
|
||||
|
||||
For example, the render hook template below adds an anchor link to the right of each heading.
|
||||
For example, the _render hook_ template below adds an anchor link to the right of each heading.
|
||||
|
||||
```go-html-template {file="layouts/_markup/heading.html"}
|
||||
<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
|
||||
@@ -336,9 +355,9 @@ Learn more about [render hook templates](/render-hooks/).
|
||||
|
||||
## Shortcode
|
||||
|
||||
A shortcode template is used to render a component of your site. Unlike [partial templates](#partial) or [content view templates](#content-view), shortcode templates are called from content pages.
|
||||
A _shortcode_ template is used to render a component of your site. Unlike _partial_ or _content view_ templates, _shortcode_ templates are called from content pages.
|
||||
|
||||
For example, the shortcode template below renders an audio element from a [global resource](g).
|
||||
For example, the _shortcode_ template below renders an audio element from a [global resource](g).
|
||||
|
||||
```go-html-template {file="layouts/_shortcodes/audio.html"}
|
||||
{{ with resources.Get (.Get "src") }}
|
||||
@@ -367,15 +386,16 @@ Use other specialized templates to create:
|
||||
[`block`]: /functions/go-template/block/
|
||||
[`ByCount`]: /methods/taxonomy/bycount/
|
||||
[`Data`]: /methods/page/data/
|
||||
[`define`]: /functions/go-template/define/
|
||||
[`partial`]: /functions/partials/include/
|
||||
[`partialCached`]: /functions/partials/includeCached/
|
||||
[`Render`]: /methods/page/render/
|
||||
[`Taxonomy`]: /methods/taxonomy/
|
||||
[`Terms`]: /methods/page/data/#terms
|
||||
[`Term`]: /methods/page/data/#term
|
||||
[`Terms`]: /methods/page/data/#terms
|
||||
[taxonomy-plural]: /methods/page/data/#plural
|
||||
[taxonomy-singular]: /methods/page/data/#singular
|
||||
[template comment]: /templates/introduction/#comments
|
||||
[template lookup order]: /templates/lookup-order/
|
||||
[term-plural]: /methods/page/data/#plural-1
|
||||
[term-singular]: /methods/page/data/#singular-1
|
||||
[base template]: #base
|
||||
|
||||
@@ -48,7 +48,7 @@ Why can't I see any of a page's descendants?
|
||||
What is the difference between an `index.md` file and an `_index.md` file?
|
||||
: A directory with an `index.md file` is a [leaf bundle](g). A directory with an `_index.md` file is a [branch bundle](g). See [details](/content-management/page-bundles/).
|
||||
|
||||
Why is my partial template not rendered as expected?
|
||||
Why is my _partial_ template not rendered as expected?
|
||||
: You may have neglected to pass the required [context](g) when calling the partial. For example:
|
||||
|
||||
```go-html-template
|
||||
@@ -66,7 +66,7 @@ When I paginate a list page, why is the page collection not filtered as specifie
|
||||
: You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/).
|
||||
|
||||
Why are there two ways to call a shortcode?
|
||||
: Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
|
||||
: Use the `{{%/* shortcode */%}}` notation if the _shortcode_ template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
|
||||
`{{</* shortcode */>}}` notation. See [details](/content-management/shortcodes/#notation).
|
||||
|
||||
Can I use environment variables to control configuration?
|
||||
@@ -85,7 +85,7 @@ Why isn't Hugo's development server detecting file changes?
|
||||
In these cases, instead of monitoring native file system events, use the `--poll` command line flag. For example, to poll the project files every 700 milliseconds, use `--poll 700ms`.
|
||||
|
||||
Why is my page Store missing a value?
|
||||
: The [`Store`] method on a `Page` object allows you to create a [scratch pad](g) on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
|
||||
: The [`Store`] method on a `Page` object allows you to create a [scratch pad](g) on the given page to store and manipulate data. Values are often set within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
|
||||
|
||||
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
|
||||
|
||||
|
||||
@@ -69,7 +69,7 @@ maximum duration
|
||||
: The maximum time spent executing the template.
|
||||
|
||||
cache potential
|
||||
: Displayed as a percentage, any partial template with a 100% cache potential should be called with the [`partialCached`] function instead of the [`partial`] function. See the [caching](#caching) section below.
|
||||
: Displayed as a percentage, any _partial_ template with a 100% cache potential should be called with the [`partialCached`] function instead of the [`partial`] function. See the [caching](#caching) section below.
|
||||
|
||||
percent cached
|
||||
: The number of times the rendered templated was cached divided by the number of times the template was executed.
|
||||
@@ -88,7 +88,7 @@ template
|
||||
|
||||
## Caching
|
||||
|
||||
Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates.
|
||||
Some _partial_ templates such as sidebars or menus are executed many times during a site build. Depending on the content within the _partial_ template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for _partial_ templates.
|
||||
|
||||
> [!note]
|
||||
> Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
|
||||
|
||||
Reference in New Issue
Block a user