Skip to content

Commit 2e9e08e

Browse files
jmooringjmooring
committed
content: Update to align with v0.146.0 template system (phase 2)
1 parent 2ec625a commit 2e9e08e

File tree

8 files changed

+158
-49
lines changed

8 files changed

+158
-49
lines changed

‎content/en/content-management/front-matter.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ lastmod
7474
: (`string`) The date that the page was last modified. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Lastmod`] method on a `Page` object.
7575

7676
layout
77-
: (`string`) Provide a template name to [target a specific template], overriding the default [template lookup order]. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the [`Layout`] method on a `Page` object.
77+
: (`string`) A custom layout name to target a specific template. For example, set the value to `foo` to use `layouts/foo.html` when rendering the current page. Access this value from a template using the [`Layout`] method on a `Page` object.
7878

7979
linkTitle
8080
: (`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`] method on a `Page` object.

‎content/en/content-management/sections.md‎

Lines changed: 8 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
title: Sections
33
description: Organize content into sections.
4-
54
categories: []
65
keywords: []
76
aliases: [/content/sections/]
@@ -47,7 +46,7 @@ content/
4746
└── about.md
4847
```
4948

50-
The example above has two top-level sections: articles and products. None of the directories under articles are sections, while all of the directories under products are sections. A section within a section is a known as a nested section or subsection.
49+
The example above has two top-level sections: articles and products. None of the directories under articles are sections, while all of the directories under products are sections. A section within a section is known as a nested section or subsection.
5150

5251
## Explanation
5352

@@ -62,30 +61,10 @@ Have list pages|:heavy_check_mark:|:x:
6261
With the file structure from the [example above](#overview):
6362

6463
1. The list page for the articles section includes all articles, regardless of directory structure; none of the subdirectories are sections.
65-
1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections.
66-
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.
64+
1. The `articles/2022` and `articles/2023` directories do not have list pages; they are not sections.
65+
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.
6766
1. All directories in the products section have list pages; each directory is a section.
6867

69-
## Template selection
70-
71-
Hugo has a defined [lookup order] to determine which template to use when rendering a page. The [lookup rules] consider the top-level section name; subsection names are not considered when selecting a template.
72-
73-
With the file structure from the [example above](#overview):
74-
75-
Content directory|Section template
76-
:--|:--
77-
`content/products`|`layouts/products/section.html`
78-
`content/products/product-1`|`layouts/products/section.html`
79-
`content/products/product-1/benefits`|`layouts/products/section.html`
80-
81-
Content directory|Page template
82-
:--|:--
83-
`content/products`|`layouts/products/page.html`
84-
`content/products/product-1`|`layouts/products/page.html`
85-
`content/products/product-1/benefits`|`layouts/products/page.html`
86-
87-
If you need to use a different template for a subsection, specify `type` and/or `layout` in front matter.
88-
8968
## Ancestors and descendants
9069

9170
A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview):
@@ -94,7 +73,7 @@ A section has one or more ancestors (including the home page), and zero or more
9473
content/products/product-1/benefits/benefit-1.md
9574
```
9675

97-
The content file (benefit-1.md) has four ancestors: benefits, product-1, products, and the home page. This logical relationship allows us to use the `.Parent` and `.Ancestors` methods to traverse the site structure.
76+
The content file `benefit-1` has four ancestors: `benefits`, `product-1`, `products`, and the home page. This logical relationship allows us to use the [`Parent`][] and [`Ancestors`][] methods to traverse the site structure.
9877

9978
For example, use the `.Ancestors` method to render breadcrumb navigation.
10079

@@ -135,5 +114,7 @@ Hugo renders this, where each breadcrumb is a link to the corresponding page:
135114
Home » Products » Product 1 » Benefits » Benefit 1
136115
```
137116

138-
[lookup order]: /templates/lookup-order/
139-
[lookup rules]: /templates/lookup-order/#lookup-rules
117+
[`Parent`]: /methods/page/parent/
118+
[`Ancestors`]: /methods/page/ancestors/
119+
[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/
120+
[`Pages`]: /methods/page/pages/

‎content/en/templates/embedded.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@ weight: 180
77
aliases: [/templates/internal]
88
---
99

10-
{{< newtemplatesystem >}}
11-
1210
## Disqus
1311

1412
> [!note]

‎content/en/templates/introduction.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@ keywords: []
77
weight: 10
88
---
99

10-
{{< newtemplatesystem >}}
11-
1210
{{% glossary-term template %}}
1311

1412
Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page.

‎content/en/templates/lookup-order.md‎

Lines changed: 96 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,106 @@
11
---
22
title: Template lookup order
33
linkTitle: Lookup order
4-
description: Hugo uses the rules below to select a template for a given page, starting from the most specific.
4+
description: Hugo selects templates by prioritizing the most specific match for each page, considering various factors to make that choice.
55
categories: []
66
keywords: []
77
weight: 20
88
---
99

10-
{{< newtemplatesystem >}}
10+
> [!note]
11+
> Hugo [v0.146.0][] introduced a fully revised template system, with significant updates to:
12+
>
13+
> - File names
14+
> - Directory structure
15+
> - Lookup order
16+
>
17+
> When upgrading a site, theme, or module, please consult the [summary of changes][] for important migration details.
18+
19+
## File names
20+
21+
The file name of each template in the `layouts` directory consists of two or more of the following identifiers separated by a dot:
22+
23+
Identifier|Description|Example file name
24+
:--|:--|:--
25+
base&nbsp;layout|Limited to [`baseof`][]|`baseof.html`
26+
custom&nbsp;layout|The value of the [`layout`][] front matter field, if any|`foo.html`
27+
page&nbsp;kind|One of [`home`][], [`page`][], [`section`][], [`taxonomy`][], or [`term`][]|`home.html`
28+
standard&nbsp;layout|Either [`list`][] or [`single`][]|`list.html`
29+
output&nbsp;format|The name of a configured [output format][]|`section.rss.xml`
30+
fallback&nbsp;layout|Limited to [`all`][]|`all.html`
31+
language|The key associated with a configured [language][]|`page.en.html`
32+
suffix|A configured suffix of the [media type][] associated with the output format |`section.rss.xml`
33+
designator|An arbitrary string, without dots, applicable to [partial], [shortcode], [content&nbsp;view][content view], and [render&nbsp;hook][render hook] templates.|`my-shortcode.html`
34+
35+
Notes:
36+
37+
1. The first identifier must be the base layout or designator, if applicable. The last identifier must be the suffix. The order of the other identifiers within the name is irrelevant.
38+
39+
40+
1. Always include a suffix.
41+
1. For base templates, the base layout identifier mucs
42+
1. Never include more than one of the page kind, standard layout, or fallback layout identifiers. For example, `home.html` is a valid file name, but `home.single.all.html` is not.
43+
1. In some cases the output format and suffix may have the same value. For example, the primary suffix of the `text/html` media type is `html`, and the `text/html` media type is associated with the `html` output format. In these cases you may provide one or both of the identifiers. For example, either `page.html.html` or `page.html` is correct. If both are provided, Hugo will choose the shortest file name.
44+
1. File names with invalid identifiers are not considered during template selection. For example, a template named `page.foo.bar.html` contains an invalid identifier, and will not be considered during template selection. While both `foo` and `bar` are valid custom layout identifiers, the file name may only contain _one_ custom layout identifier.
45+
46+
Template file names follow this pattern, with a minimum of two identifiers, where the `designator` is only applicable to partial, shortcode, content view, and render hook templates:
47+
48+
```text
49+
[designator].[page kind]|[standard layout]|[fallback layout].[custom layout].[language].[output format].[suffix]
50+
```
51+
52+
Examples:
1153

54+
- `all.html.html`
55+
- `list.html.html`
56+
- `page.html.html`
57+
- `mylayout.html.html`
58+
- `mylayout.en.html.html`
59+
- `page.mylayout.html.html`
60+
- `page.mylayout.en.html.html`
61+
- `page.en.html.html`
62+
63+
As noted earlier, when the output format and suffix have the same value, you may omit the output format identifier. For example, the list above is equivalent to:
64+
65+
- `all.html`
66+
- `list.html`
67+
- `page.html`
68+
- `mylayout.html`
69+
- `mylayout.en.html`
70+
- `page.mylayout.html`
71+
- `page.mylayout.en.html`
72+
- `page.en.html`
73+
74+
[`all`]: /templates/types/#all
75+
[`baseof`]: /templates/types/#base
76+
[`home`]: /templates/types/#home
77+
[`layout`]: /content-management/front-matter/#layout
78+
[`list`]: /templates/types/#list
79+
[`page`]: /templates/types/#page
80+
[`section`]: /templates/types/#section
81+
[`single`]: /templates/types/#single
82+
[`taxonomy`]: /templates/types/#taxonomy
83+
[`term`]: /templates/types/#term
84+
[content view]: /templates/types/#content-view
85+
[language]: /configuration/languages/
86+
[media type]: /configuration/media-types/
87+
[output format]: /configuration/output-formats/
88+
[partial]: /templates/types/#partial
89+
[render hook]: /templates/types/#render-hook
90+
[shortcode]: /templates/types/#shortcode
91+
[summary of changes]: /templates/new-templatesystem-overview/
92+
[v0.146.0]: https://github.com/gohugoio/hugo/releases/tag/v0.146.0
93+
94+
## Directory structure
95+
96+
97+
Symetricals
98+
99+
100+
101+
102+
103+
<!--
12104
## Lookup rules
13105
14106
Hugo takes the parameters listed below into consideration when choosing a template for a given page. The templates are ordered by specificity. This should feel natural, but look at the table below for concrete examples of the different parameter variations.
@@ -93,3 +185,5 @@ layouts/
93185
└── contact.html <-- renders contact.md
94186
└── single.html <-- renders about.md
95187
```
188+
189+
-->

‎content/en/templates/new-templatesystem-overview.md‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,11 +89,62 @@ layouts
8989
└── list.html
9090
```
9191

92+
## Pages in content root
93+
94+
Consider this content structure:
95+
96+
```text
97+
content/
98+
├── _index.md
99+
├── about.md
100+
└── contact.md
101+
```
102+
103+
To create unique templates for both `about.md` and `contact.md`, use the template structure below:
104+
105+
```text
106+
layouts/
107+
├── about/
108+
│ └── page.html <-- renders content/about.md
109+
├── contact/
110+
│ └── page.html <-- renders content/contact.md
111+
├── baseof.html
112+
├── home.html <-- renders content/_index_.md
113+
├── page.html
114+
├── section.html
115+
├── taxonomy.html
116+
└── term.html
117+
```
118+
119+
Alternatively, you may specify `layout` in front matter:
120+
121+
{{< code-toggle file=content/about.md fm=true >}}
122+
title: About
123+
layout: about
124+
{{< /code-toggle >}}
125+
126+
{{< code-toggle file=content/content.md fm=true >}}
127+
title: Content
128+
layout: content
129+
{{< /code-toggle >}}
130+
131+
```text
132+
layouts/
133+
├── about.html <-- renders content/about.md
134+
├── contact.html <-- renders content/contact.md
135+
├── baseof.html
136+
├── home.html <-- renders content/_index_.md
137+
├── page.html
138+
├── section.html
139+
├── taxonomy.html
140+
└── term.html
141+
```
142+
92143
[^type]: The `type` set in front matter will effectively replace the `section` folder in [Page path] when doing lookups.
93144
[^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.
94145

95146
[Example folder structure]: #example-folder-structure
96147
[Hugo v0.146.0]: https://github.com/gohugoio/hugo/releases/tag/v0.146.0
97-
[Page kinds]: https://gohugo.io/methods/page/kind/
98-
[Page path]: https://gohugo.io/methods/page/path/
148+
[Page kinds]: /methods/page/kind/
149+
[Page path]: /methods/page/path/
99150
[template types]: /templates/types/

‎content/en/templates/shortcode.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@ weight: 120
77
aliases: [/templates/shortcode-templates/]
88
---
99

10-
{{< newtemplatesystem >}}
11-
1210
> [!note]
1311
> Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates.
1412

‎layouts/_shortcodes/newtemplatesystem.html‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

0 commit comments

Comments
 (0)