Documentation of the new template system in Hugo v0.146.0

Announcements
1

See: New template system in Hugo v0.146.0

10 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