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

Merge commit '346b60358dd8ec2ca228e6635bff9d7914b398b7'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-01-23 09:47:46 +01:00
parent 7f0f50b133 346b60358d
commit 43307b07f8
384 changed files with 3305 additions and 3271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -11,7 +11,7 @@ menu:
weight: 160
---
To render a 404 error page in the root of your site, create a 404 template in the root of the layouts directory. For example:
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 >}}
{{ define "main" }}

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

@@ -13,4 +13,4 @@ weight: 10
aliases: [/templates/overview/,/templates/content]
---
A template is an HTML file with [template actions](/getting-started/glossary/#template-action), located within the layouts directory of a project, theme, or module. Visit the topics below, in the order presented, to understand template selection and creation.
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.

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

@@ -22,15 +22,15 @@ The following are common use cases for content views:
To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single template], `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
```txt
▾ layouts/
▾ posts/
li.html
single.html
summary.html
▾ project/
li.html
single.html
summary.html
layouts/
├── posts/
│ ├── li.html
│ ├── single.html
│ └── summary.html
├── project/
│ ├── li.html
│ └── single.html
└── summary.html
```
## Which template will be rendered?

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

@@ -15,7 +15,7 @@ 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:
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" . }}`
@@ -58,7 +58,7 @@ You can also set the following in the front matter for a given piece of content:
## 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:
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" . }}`
@@ -90,7 +90,7 @@ To use this value in your own template, access the configured ID with `{{ site.C
## 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:
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" . }}`
@@ -149,7 +149,7 @@ 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:
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" . }}`
@@ -170,7 +170,7 @@ 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:
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" . }}`

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

@@ -14,7 +14,6 @@ aliases: [/layout/homepage/,/templates/homepage-template/,/templates/homepage/]
The home template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website.
{{< youtube ut1xtRZ1QOA >}}
## Home template lookup order
@@ -23,7 +22,7 @@ See [Template Lookup](/templates/lookup-order/).
## Add content and front matter to the home page
The home page accepts content and front matter from an `_index.md` file. This file should live at the root of your `content` folder (i.e., `content/_index.md`). You can then add body copy and metadata to your home page the way you would any other content file.
The home page accepts content and front matter from an `_index.md` file. This file should live at the root of your `content` directory (i.e., `content/_index.md`). You can then add body copy and metadata to your home page the way you would any other content file.
See the home template below or [Content Organization][contentorg] for more information on the role of `_index.md` in adding content and front matter to list pages.

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

@@ -13,7 +13,7 @@ weight: 20
toc: true
---
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.
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.
[functions]: /functions/
[methods]: /methods/
@@ -44,10 +44,7 @@ While HTML templates are the most common, you can create templates for any [outp
## Context
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] and associated [methods].
[objects]: /getting-started/glossary/#object
[methods]: /getting-started/glossary/#method
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.
@@ -81,9 +78,7 @@ The current context may change within a template. For example, at the top of a t
{{ end }}
{{< /code >}}
In the example above, the context changes as we `range` through the [slice] 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:
[slice]: /getting-started/glossary/#slice
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:
```html
<h2>My Page Title</h2>
@@ -116,12 +111,7 @@ Make sure that you thoroughly understand the concept of _context_ before you con
In the examples above the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template.
A template action may contain literal values ([boolean], [string], [integer], and [float]), variables, functions, and methods.
[boolean]: /getting-started/glossary/#boolean
[string]: /getting-started/glossary/#string
[integer]: /getting-started/glossary/#integer
[float]: /getting-started/glossary/#float
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 >}}
{{ $convertToLower := true }}
@@ -167,9 +157,7 @@ Whitespace includes spaces, horizontal tabs, carriage returns, and newlines.
### Pipes
Within a template action you may [pipe] a value to a function or method. The piped value becomes the final argument to the function or method. For example, these are equivalent:
[pipe]: /getting-started/glossary/#pipeline
Within a template action you may [pipe](g) a value to a function or method. The piped value becomes the final argument to the function or method. For example, these are equivalent:
```go-html-template
{{ strings.ToLower "Hugo" }} → hugo
@@ -207,9 +195,7 @@ You can split a template action over two or more lines. For example, these are e
}}
```
You can also split [raw string literals] over two or more lines. For example, these are equivalent:
[raw string literals]: /getting-started/glossary/#string-literal-raw
You can also split [raw string literals](g) over two or more lines. For example, these are equivalent:
```go-html-template
{{ $msg := "This is line one.\nThis is line two." }}
@@ -221,16 +207,9 @@ This is line two.`
## Variables
A variable is a user-defined [identifier] prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
A variable is a user-defined [identifier](g) prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
[identifier]: /getting-started/glossary/#identifier
Variables may contain [scalars], [slices], [maps], or [objects].
[scalars]: /getting-started/glossary/#scalar
[slices]: /getting-started/glossary/#slice
[maps]: /getting-started/glossary/#map
[objects]: /getting-started/glossary/#object
Variables may contain [scalars](g), [slices](g), [maps](g), or [objects](g).
Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. For example:
@@ -260,9 +239,7 @@ With variables that represent a slice or map, use the [`index`] function to retu
Slices and arrays are zero-based; element 0 is the first element.
{{% /note %}}
With variables that represent a map or object, [chain] identifiers to return the desired value or to access the desired method.
[chain]: /getting-started/glossary/#chain
With variables that represent a map or object, [chain](g) identifiers to return the desired value or to access the desired method.
```go-html-template
{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
@@ -317,7 +294,7 @@ Object|Method|Description
`Page`|[`Date`](methods/page/date/)|Returns the date of the given page.
`Page`|[`Params`](methods/page/params/)|Returns a map of custom parameters as defined in the front matter of the given page.
`Page`|[`Title`](methods/page/title/)|Returns the title of the given page.
`Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the data directory.
`Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the `data` directory.
`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in the site configuration.
`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the site configuration.
@@ -399,7 +376,7 @@ Use the [`template`] function to include one or more of Hugo's [embedded templat
[`partial`]: /functions/partials/include/
[`partialCached`]: /functions/partials/includecached/
[`template`]: functions/go-template/template/
[`template`]: /functions/go-template/template/
Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:

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

@@ -37,7 +37,7 @@ Section
: Is relevant for `section`, `taxonomy` and `term` types.
{{% note %}}
Templates can live in either the project's or the themes' layout folders, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.
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 %}}
## Target a template
@@ -52,9 +52,7 @@ content/
└── contact.md
```
Files in the root of the content directory have a [content type] of `page`. To render these pages with a unique template, create a matching subdirectory:
[content type]: /getting-started/glossary/#content-type
Files in the root of the `content` directory have a [content type](g) of `page`. To render these pages with a unique template, create a matching subdirectory:
```text
layouts/

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

@@ -27,7 +27,7 @@ The most common templating mistake related to pagination is invoking pagination
## Terminology
paginate
: To split a [list page] into two or more subsets.
: To split a [list page](g) into two or more subsets.
pagination
: The process of paginating a list page.
@@ -38,8 +38,6 @@ pager
paginator
: A collection of pagers.
[list page]: /getting-started/glossary/#list-page
## Configuration
Control pagination behavior in your site configuration. These are the default settings:
@@ -116,11 +114,10 @@ To paginate a list page using the `Paginate` method:
In the example above, we:
1. Build a page collection
2. Sort the page collection by title
3. Paginate the page collection, with 7 pages per pager
4. Range over the paginated page collection, rendering a link to each page
5. Call the embedded pagination template to create navigation links between pagers
1. Sort the page collection by title
1. Paginate the page collection, with 7 pages per pager
1. Range over the paginated page collection, rendering a link to each page
1. Call the embedded pagination template to create navigation links between pagers
To paginate a list page using the `Paginator` method:
@@ -135,8 +132,8 @@ To paginate a list page using the `Paginator` method:
In the example above, we:
1. Paginate the page collection passed into the template, with the default number of pages per pager
2. Range over the paginated page collection, rendering a link to each page
3. Call the embedded pagination template to create navigation links between pagers
1. Range over the paginated page collection, rendering a link to each page
1. Call the embedded pagination template to create navigation links between pagers
## Caching
@@ -193,7 +190,7 @@ The `terse` format has fewer controls and page slots, consuming less space when
```
{{% 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:
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" . }}`

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

@@ -27,8 +27,7 @@ layouts/
├── head/
│ ├── favicons.html
│ ├── metadata.html
│ ├── prerender.html
│ └── twitter.html
│ └── prerender.html
└── header/
├── site-header.html
└── site-nav.html

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

@@ -33,7 +33,7 @@ Search engines that honor the Robots Exclusion Protocol will interpret this as p
You may overwrite the internal template with a custom template. Hugo selects the template using this lookup order:
1. `/layouts/robots.txt`
2. `/themes/<THEME>/layouts/robots.txt`
1. `/themes/<THEME>/layouts/robots.txt`
## robots.txt template example
@@ -50,9 +50,9 @@ This template creates a robots.txt file with a `Disallow` directive for each pag
To create a robots.txt file without using a template:
1. Set `enableRobotsTXT` to `false` in the site configuration.
2. Create a robots.txt file in the `static` directory.
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.
Remember that Hugo copies everything in the [`static` directory][static] to the root of `publishDir` (typically `public`) when you build your site.
[static]: /getting-started/directory-structure/
{{% /note %}}

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

@@ -23,9 +23,7 @@ taxonomy = ['html']
term = ['html']
{{< /code-toggle >}}
To disable feed generation for all [page kinds]:
[page kinds]: /getting-started/glossary/#page-kind
To disable feed generation for all [page kinds](g):
{{< code-toggle file=hugo >}}
disableKinds = ['rss']

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

@@ -43,21 +43,21 @@ Hugo selects shortcode templates based on the shortcode name, the current output
Shortcode name|Output format|Language|Template path
:--|:--|:--|:--
foo|html|en|layouts/shortcodes/foo.en.html
foo|html|en|layouts/shortcodes/foo.html.html
foo|html|en|layouts/shortcodes/foo.html
foo|html|en|layouts/shortcodes/foo.html.en.html
foo|html|en|`layouts/shortcodes/foo.en.html`
foo|html|en|`layouts/shortcodes/foo.html.html`
foo|html|en|`layouts/shortcodes/foo.html`
foo|html|en|`layouts/shortcodes/foo.html.en.html`
Shortcode name|Output format|Language|Template path
:--|:--|:--|:--
foo|rss|en|layouts/shortcodes/foo.en.xml
foo|rss|en|layouts/shortcodes/foo.rss.xml
foo|rss|en|layouts/shortcodes/foo.en.html
foo|rss|en|layouts/shortcodes/foo.rss.en.xml
foo|rss|en|layouts/shortcodes/foo.xml
foo|rss|en|layouts/shortcodes/foo.html.en.html
foo|rss|en|layouts/shortcodes/foo.html.html
foo|rss|en|layouts/shortcodes/foo.html
foo|rss|en|`layouts/shortcodes/foo.en.xml`
foo|rss|en|`layouts/shortcodes/foo.rss.xml`
foo|rss|en|`layouts/shortcodes/foo.en.html`
foo|rss|en|`layouts/shortcodes/foo.rss.en.xml`
foo|rss|en|`layouts/shortcodes/foo.xml`
foo|rss|en|`layouts/shortcodes/foo.html.en.html`
foo|rss|en|`layouts/shortcodes/foo.html.html`
foo|rss|en|`layouts/shortcodes/foo.html`
Note that templates provided by a theme or module always take precedence.
@@ -415,8 +415,8 @@ The same inline shortcode can be reused later in the same content file, with dif
[`Name`]: /methods/shortcode/name/
[`Position`]: /methods/shortcode/position/
[built-in shortcode]: /content-management/shortcodes/
[figure]: /content-management/shortcodes/#figure
[figure]: /shortcodes/figure/
[lookup order]: /templates/lookup-order/
[source organization]: /getting-started/directory-structure/
[vimeoexample]: #single-flexible-example-vimeo
[youtubeshortcode]: /content-management/shortcodes/#youtube
[youtubeshortcode]: /shortcodes/youtube/

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

@@ -60,15 +60,15 @@ title = 'News'
To override the built-in sitemap.xml template, create a new file in either of these locations:
- layouts/sitemap.xml
- layouts/_default/sitemap.xml
- `layouts/sitemap.xml`
- `layouts/_default/sitemap.xml`
When ranging through the page collection, access the _change frequency_ and _priority_ with `.Sitemap.ChangeFreq` and `.Sitemap.Priority` respectively.
To override the built-in sitemapindex.xml template, create a new file in either of these locations:
- layouts/sitemapindex.xml
- layouts/_default/sitemapindex.xml
- `layouts/sitemapindex.xml`
- `layouts/_default/sitemapindex.xml`
## Disable sitemap generation
@@ -79,4 +79,4 @@ disableKinds = ['sitemap']
{{</ code-toggle >}}
[`publishDir`]: /getting-started/configuration#publishdir
[sitemap protocol]: <https://www.sitemaps.org/protocol.html>
[sitemap protocol]: https://www.sitemaps.org/protocol.html

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

@@ -12,10 +12,8 @@ toc: true
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy-templates/]
---
The [taxonomy] template below inherits the site's shell from the [base template], and renders a list of [terms] in the current taxonomy.
The [taxonomy](g) template below inherits the site's shell from the [base template], and renders a list of [terms](g) in the current taxonomy.
[taxonomy]: /getting-started/glossary/#taxonomy
[terms]: /getting-started/glossary/#term
[base template]: /templates/types/
{{< code file=layouts/_default/taxonomy.html >}}
@@ -57,9 +55,7 @@ Plural
```
Terms
: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages] associated with each term.
[weighted pages]: /getting-started/glossary/#weighted-page
: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages](g) associated with each term.
```go-html-template
{{ $taxonomyObject := .Data.Terms }}
@@ -99,9 +95,8 @@ The taxonomy template below inherits the site's shell from the base template, an
## Include content links
The [`Alphabetical`] and [`ByCount`] methods used in the previous examples return an [ordered taxonomy], so we can also list the content to which each term is assigned.
The [`Alphabetical`] and [`ByCount`] methods used in the previous examples return an [ordered taxonomy](g), so we can also list the content to which each term is assigned.
[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy
[`Alphabetical`]: /methods/taxonomy/alphabetical/
[`ByCount`]: /methods/taxonomy/bycount/
@@ -124,7 +119,7 @@ The taxonomy template below inherits the site's shell from the base template, an
## Display metadata
Display metadata about each term by creating a corresponding branch bundle in the content directory.
Display metadata about each term by creating a corresponding branch bundle in the `content` directory.
For example, create an "authors" taxonomy:
@@ -133,9 +128,7 @@ For example, create an "authors" taxonomy:
author = 'authors'
{{< /code-toggle >}}
Then create content with one [branch bundle] for each term:
[branch bundle]: /getting-started/glossary/#branch-bundle
Then create content with one [branch bundle](g) for each term:
```text
content/

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

@@ -11,9 +11,8 @@ weight: 100
toc: true
---
The [term] template below inherits the site's shell from the [base template], and renders a list of pages associated with the current term.
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.
[term]: /getting-started/glossary/#term
[base template]: /templates/types/
{{< code file=layouts/_default/term.html >}}
@@ -63,7 +62,7 @@ Term
## Display metadata
Display metadata about each term by creating a corresponding branch bundle in the content directory.
Display metadata about each term by creating a corresponding branch bundle in the `content` directory.
For example, create an "authors" taxonomy:
@@ -72,9 +71,7 @@ For example, create an "authors" taxonomy:
author = 'authors'
{{< /code-toggle >}}
Then create content with one [branch bundle] for each term:
[branch bundle]: /getting-started/glossary/#branch-bundle
Then create content with one [branch bundle](g) for each term:
```text
content/

14
docs/content/en/templates/types/index.md
View File

@@ -17,7 +17,7 @@ aliases: ['/templates/lists/']
## Structure
Create templates in the layouts directory in the root of your project.
Create templates in the `layouts` directory in the root of your project.
Although your site may not require each of these templates, the example below is typical for a site of medium complexity.
@@ -142,9 +142,7 @@ Learn more about [section templates](/templates/section/).
## Taxonomy
A taxonomy template renders a list of terms in a [taxonomy].
[taxonomy]: /getting-started/glossary/#taxonomy
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.
@@ -164,9 +162,7 @@ Learn more about [taxonomy templates](/templates/taxonomy/).
## Term
A term template renders a list of pages associated with a [term].
[term]: /getting-started/glossary/#term
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.
@@ -256,9 +252,7 @@ Learn more about [render hook templates](/render-hooks/).
A shortcode template is used to render a component of your site. Unlike partial templates, shortcode templates are called from content pages.
For example, the shortcode template below renders an audio element from a [global resource].
[global resource]: /getting-started/glossary/#global-resource
For example, the shortcode template below renders an audio element from a [global resource](g).
{{< code file=layouts/shortcodes/audio.html >}}
{{ with resources.Get (.Get "src") }}