mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-24 15:28:54 +00:00
Add a one pager about the new template system
This commit is contained in:
Bjørn Erik Pedersen
@@ -7,6 +7,8 @@ weight: 40
|
||||
aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary.
|
||||
|
||||
{{< youtube QVOMCYitLEc >}}
|
||||
|
||||
@@ -7,6 +7,8 @@ weight: 110
|
||||
aliases: [/templates/views/]
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
The following are common use cases for content views:
|
||||
|
||||
- You want content of every type to be shown on the home page but only with limited [summary views][summaries].
|
||||
|
||||
@@ -7,6 +7,8 @@ weight: 170
|
||||
aliases: [/templates/internal]
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
## Disqus
|
||||
|
||||
> [!note]
|
||||
|
||||
@@ -7,6 +7,9 @@ weight: 50
|
||||
aliases: [/layout/homepage/,/templates/homepage-template/,/templates/homepage/]
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
|
||||
## Introduction
|
||||
|
||||
A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages.
|
||||
|
||||
@@ -7,6 +7,9 @@ keywords: []
|
||||
weight: 10
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
|
||||
{{% glossary-term template %}}
|
||||
|
||||
Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page.
|
||||
|
||||
@@ -7,6 +7,8 @@ keywords: []
|
||||
weight: 20
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
## Lookup rules
|
||||
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
|
||||
---
|
||||
title: New template system in Hugo v0.146.0
|
||||
linktitle: New template system
|
||||
description: Overview of the new template system in Hugo v0.146.0.
|
||||
categories: []
|
||||
keywords: []
|
||||
weight: 1
|
||||
---
|
||||
|
||||
In [Hugo v0.146.0], we performed a full re-implementation of how Go templates are handled in Hugo. This includes structural changes to the `layouts` folder and a new, more powerful template lookup system.
|
||||
|
||||
We have aimed to maintain as much backward compatibility as possible by mapping "old to new," but some reported breakages have occurred. We're working on a full overhaul of the documentation on this topic – until then, this is a one-pager with the most important changes.
|
||||
|
||||
## Changes to the `layouts` folder
|
||||
|
||||
| Description | Action required |
|
||||
| ------------- | ------------- |
|
||||
| The `_default` folder is removed. | Move all files in `layouts/_default` up to the `layouts/` root.|
|
||||
| The `layouts/partials` folder is renamed to `layouts/_partials`. | Rename the folder. |
|
||||
| The `layouts/shortcodes` folder is renamed to `layouts/_shortcodes`. | Rename the folder. |
|
||||
| Any folder in `layouts` that does not start with `_` represents the root of a [Page path]. In [Hugo v0.146.0], this can be nested as deeply as needed, and `_shortcodes` and `_markup` folders can be placed at any level in the tree.| No action required.|
|
||||
| The above also means that there's no top-level `layouts/taxonomy` folder anymore, unless this represents a [Page path].|Move them up to `layouts/` with one of the [Page kinds] `taxonomy` or `term` as the base name, or place the layouts into the taxonomy [Page path]. |
|
||||
| For base templates (e.g., `baseof.html`), in previous Hugo versions, you could prepend one identifier (layout, type, or kind) with a hyphen in front of the baseof keyword.|Move that identifier after the first "dot," e.g., rename`list-baseof.html` to `baseof.list.html`.|
|
||||
| We have added a new `all` "catch-all" layout. This means that if you have, e.g., `layouts/all.html` and that is the only template, that layout will be used for all HTML page rendering.||
|
||||
| We have removed the concept of `_internal` Hugo templates.[^internal]|Replace constructs similar to `{{ template "_internal/opengraph.html" . }}` with `{{ partial "opengraph.html" . }}`.|
|
||||
| The identifiers that can be used in a template filename are one of the [Page kinds] (`home`, `page`, `section`, `taxonomy`, or `term`), one of the standard layouts (`list`, `single`, or `all`), a custom layout (as defined in the `layout` front matter field), a language (e.g., `en`), an output format (e.g., `html`, `rss`), and a suffix representing the media type. E.g., `all.en.html` and `home.rss.xml`.||
|
||||
| The above means that there's no such thing as an `index.html` template for the home page anymore. | Rename `index.html` to `home.html`.|
|
||||
|
||||
Also, see the [Example folder structure] below for a more concrete example of the new layout system.
|
||||
|
||||
## 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.
|
||||
|
||||
The identifiers used in the template weighting, in order of importance, are:
|
||||
|
||||
| Identifier | Description |
|
||||
| ---------- | ----------- |
|
||||
| Layout custom | The custom `layout` set in front matter. |
|
||||
| [Page kinds] | One of `home`, `section`, `taxonomy`, `term`, `page`. |
|
||||
| Layouts standard 1 | `list` or `single`. |
|
||||
| Output format | The output format (e.g., `html`, `rss`). |
|
||||
| Layouts standard 2 | `all`. |
|
||||
| Language | The language (e.g., `en`). |
|
||||
| Media type | The media type (e.g., `text/html`). |
|
||||
| [Page path] | The page path (e.g., `/blog/mypost`). |
|
||||
| Type | `type` set in front matter.[^type]|
|
||||
|
||||
For templates placed in a `layouts` folder partly or completely matching a [Page path], a closer match upwards will be considered _better_. In the [Example folder structure] below, this means that:
|
||||
|
||||
* `layouts/docs/api/_markup/render-link.html` will be used to render links from the Page path `/docs/api` and below.
|
||||
* `layouts/docs/baseof.html` will be used as the base template for the Page path `/docs` and below.
|
||||
* `layouts/tags/term.html` will be used for all `term` rendering in the `tags` taxonomy, except for the `blue` term, which will use `layouts/tags/blue/list.html`.
|
||||
|
||||
## Example folder structure
|
||||
|
||||
```
|
||||
layouts
|
||||
├── baseof.html
|
||||
├── baseof.term.html
|
||||
├── home.html
|
||||
├── list.html
|
||||
├── single.html
|
||||
├── taxonomy.html
|
||||
├── term.html
|
||||
├── term.mylayout.en.rss.xml
|
||||
├── _markup
|
||||
│ ├── render-codeblock-go.term.mylayout.no.rss.xml
|
||||
│ └── render-link.html
|
||||
├── _partials
|
||||
│ └── mypartial.html
|
||||
├── _shortcodes
|
||||
│ ├── myshortcode.html
|
||||
│ └── myshortcode.section.mylayout.en.rss.xml
|
||||
├── docs
|
||||
│ ├── baseof.html
|
||||
│ ├── _shortcodes
|
||||
│ │ └── myshortcode.html
|
||||
│ └── api
|
||||
│ ├── mylayout.html
|
||||
│ ├── single.html
|
||||
│ └── _markup
|
||||
│ └── render-link.html
|
||||
└── tags
|
||||
├── taxonomy.html
|
||||
├── term.html
|
||||
└── blue
|
||||
└── 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.
|
||||
|
||||
@@ -7,6 +7,9 @@ weight: 70
|
||||
aliases: [/templates/sections/,/templates/section-templates/]
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
|
||||
## Add content and front matter to section templates
|
||||
|
||||
To effectively leverage section templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages.
|
||||
|
||||
@@ -7,6 +7,9 @@ weight: 120
|
||||
aliases: [/templates/shortcode-templates/]
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
|
||||
> [!note]
|
||||
> Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates.
|
||||
|
||||
|
||||
@@ -7,6 +7,9 @@ weight: 60
|
||||
aliases: [/layout/content/,/templates/single-page-templates/]
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
|
||||
The single template below inherits the site's shell from the [base template].
|
||||
|
||||
[base template]: /templates/types/
|
||||
|
||||
@@ -7,6 +7,9 @@ weight: 80
|
||||
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy-templates/]
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
|
||||
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.
|
||||
|
||||
[base template]: /templates/types/
|
||||
|
||||
@@ -6,6 +6,9 @@ keywords: []
|
||||
weight: 90
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
|
||||
The [term](g) template below inherits the site's shell from the [base template], and renders a list of pages associated with the current term.
|
||||
|
||||
[base template]: /templates/types/
|
||||
|
||||
@@ -7,6 +7,9 @@ weight: 30
|
||||
aliases: ['/templates/lists/']
|
||||
---
|
||||
|
||||
{{< newtemplatesystem >}}
|
||||
|
||||
|
||||
## Structure
|
||||
|
||||
Create templates in the `layouts` directory in the root of your project.
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
{{ $text := `We did a complete overhaul of Hugo's template system in v0.146.0.
|
||||
We're working on getting all of the relevant documentation up to date, but until
|
||||
then, see [this page](/templates/new-templatesystem-overview/). `
|
||||
}}
|
||||
{{ partial "layouts/blocks/alert.html"
|
||||
(dict
|
||||
"color" "orange"
|
||||
"icon" "information-circle"
|
||||
"text" ($text | $.Page.RenderString )
|
||||
"title" ""
|
||||
"class" "text-black")
|
||||
}}
|
||||
Reference in New Issue
Block a user