Documentation of the new template system in Hugo v0.146.0

Announcements
1

See: New template system in Hugo v0.146.0

12 Likes
3

I saw a comment by Joe with page.html instead of single.html. Is one mapped to the other?

4

I’m not sure about how it works under the hood, but I think this structure is the easiest to understand, at least for new users:

layouts/
├── baseof.html
├── home.html
├── page.html
├── section.html
├── taxonomy.html
└── term.html

That way, excluding the base template, there’s a one-to-one relationship between page kind and template. The structure above is what you get with hugo new theme.

5 Likes
5

Yea, I agree. Feel free to simplify/improve my example.

They’re both valid. See the table in New template system in Hugo v0.146.0

  • single is a layout, currently only used for the page kind.
  • page is Page kind.

For most practical applications, they work the same, but if you have both page.html and single.html, the first one will win (see the table linked to above).

So, why didn’t we remove single from the equation?

  1. We may get more “single kinds” in the future.
  2. But mostly because there’s sooooo many Hugo sites in the wild with a single.html and list.html template that changing that would create more noise than the value.
3 Likes
6

Excellent explanation. I went with page as I found it made more sense with regards to everything in content being a page.

1 Like
7

sounds very reasonable … maybe a deprecation candidate vor v1 or when time did its work and usage of single is lesser

3 Likes
8

This sounds like a huge job at first, but I moved 6 websites to new template system and observed no issues, but instead, I found out that understanding template and what comes first is much clearer now, especially with taxonomy. Well done!

4 Likes
9

@idarek thanks, feedback much appreciated. The old setup had an extreme amount of variations, but given that, it was surprisingly inflexible. So we had to fix it, and I suspect for 99.9% of sites out there it was smooth sailing, but with many many Hugo sites accumulated over the years, it’s hard/impossible to cover all bases.

4 Likes
10

Personally, I went with this setup even in section specific folder layouts.

layouts/
├── baseof.html
├── home.html
├── page.html
├── list.html
├── taxonomy.html
└── term.html

So far so good. I also like the new layout system, especially after reading this From WordPress to Hugo, a mindset transition | Regis Philibert.

11
  1. If page.html and single.html work the same way for rendering specific pages, why this change was necessary?
  2. Section.html is a good naming, but list.html was basically the same? custom-folder within the content directory == section.
  3. And why does GoHugo create an additional template for taxonomies? It’s the most complicated part for me. Can I just filter necessary posts through Front Matter values? Something like:
---
tags: ["specific-tag-name"]
---

{{ range .Pages }}
  {{ if in .Params.tags "specific-tag-name" }}
    <h2>{{ .Title }}</h2>
  {{ end }}
{{ end }}

Then why there are taxonomy.html at all..

12

straightforward conversion of 3 sites done without issues, very clear instructions, thanks!

13

As I mentioned above, this way there’s a one-to-one relationship between page kind and template, which is much easier to understand, for new users in particular.

No. There’s a one-to-one relationship between page kind and template, with fallbacks as shown below:

page kind template lookup order
home home.html → list.html → all.html
page page.html → single.html → all.html
section section.html → list.html → all.html
taxonomy taxonomy.html → list.html → all.html
term taxonomy.html → list.html → all.html

There’s a one-to-one relationship between page kind and template. If you want a list template that can be used with section, taxonomy, and term pages, create a list.html template as shown above.

2 Likes
14

Thank you, I got it!