# How to adapt to the new template system introduced in Hugo 0.146.0?

**URL:** <https://discourse.gohugo.io/t/how-to-adapt-to-the-new-template-system-introduced-in-hugo-0-146-0/54683>\
**Category:** support\
**Created:** [May 9, 2025, 3:05am UTC](https://discourse.gohugo.io/t/how-to-adapt-to-the-new-template-system-introduced-in-hugo-0-146-0/54683 "2025-05-09T03:05:11Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![CyrusYip](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/cyrusyip/32/20786_2.png) [@CyrusYip](https://discourse.gohugo.io/u/CyrusYip)\
**Post date:** [May 9, 2025, 3:05am UTC](https://discourse.gohugo.io/t/how-to-adapt-to-the-new-template-system-introduced-in-hugo-0-146-0/54683/1 "2025-05-09T03:05:11Z")

</div>

According to these resources:

> <https://github.com/gohugoio/hugo/pull/13541>
>
> Some key differences from \`v0.145.0\`:
> 
> \* We now consider the complete \[Page.Pa…th\](https://gohugo.io/methods/page/path/), not just the top level (\`section\`/\`type\`) when resolving templates.
> \* All template lookup follows the same code path. This means that you can use the same set of identifiers in the filenames for page layouts (including base, e.g. \`baseof.list.html\`, templates), shortcode templates, and render hook templates. 
> \* \`\_shortcodes\` and \`\_markup\` directories can be added to any level in the file tree.
> \* The directories \`shortcodes\` and \`partials\` are renamed \`\_shortcodes\` and \`\_partials\`.
> \* The (confusing) concept of \`\_internal/\` templates are removed (but will still work, will be deprecated a later Hugo version), so e.g. the Twitter card template needs to be loaded via \`{{ partial "twitter\_cards.html" . }}\`.
> \* Add a new catch-all layout named \`all\`, see #13545.
> 
> \> \[!note\] 
> \>I have gone to great lengths to make this as backwards compatible as possible. All existing test passes and I have added lots more. But with the amount of Hugo sites in the wild, I would surprised if we end up with no "my site is broken" reports after releasing this, but we really need to do this.
> 
> \## Identifiers and their weights
> 
> | Name | Description | W1 | W2 | W3|
> | ------------ | ------- |:-------:|:------:|:-------:|
> | Distance | To find the best matching template, we walk from the root down to the page's \`Path\`. The \`distance\` is measured in directory levels from the page \`Path\` up to the template path. | | | |
> | Kind | The \`Page\` \`Kind\`, one of \`home\`, \`page\`, \`section\`, \`term\` or \`taxonomy\`. |3| 1| |
> | Layout Standard |\`all\`, \`list\` or \`single\`.|2| 1| |
> | Layout Custom |Custom layout set in the \`layout\` front matter key, e.g. \`mylayout\`.|4| 2| |
> |Type|Set in \`type\` front matter key. For template lookups, this effectively changes the root directory of \`Page.Path\`. ||||
> | OutputFormat |Output format name, e.g. \`html\`.| 2| | 1|
> | MediaType |Media type, e.g. \`text/html\`.| 1| | 1|
> | Lang | Language, e.g. \`en\`.| 1| | 1|
> | Variant1 |Contextual variant, currently used to identify a render hook, e.g. \`link\`.|4| | |
> | Variant2|Contextual variant, currently used to identify e.g. the code language in codeblock render hooks.| 2| | |
> 
> \## Template Resolving
> 
> This section covers template resolving for page layouts, shortcodes and render hook templates. Partials has currently a much simpler logic.
> 
> To resolve a template, we
> 
> 1. Create a Page descriptor with the identifiers listed above.
> 1. Walk the template tree down to the Page path and compare the Page descriptor with the current template descriptor.
> 1. If the template descriptor is a subset of the Page descriptor, we calculate the weights \`w1\`, \`w2\` and \`w3\`.
> 1. If this is the first match, we store it away.
> 1. Else we compare it to the previous best match:
> 1. If the new match's path is closer to the Page path than the previous best match's path, we compare their values for \`w2\` and \`w3\`, in that order. For example, given a Page path \`/foo/bar\`, a layout in \`/layouts/foo/single.html\` would win over \`/layouts/page.html\` even if the latter has a higher \`w1\` weight.
> 1. Else we compare their values for \`w1\`.
> 1. All things equal, these are the tie breakers:
> 1. Shortest distance.
> 1. If \`layout\` is set, we prefer any value before \`all\`.
> 1. The lesser layout Path (lexicographically).   
> 
> There are some special cases to the above:
> 
> \* We prefer user provided templates over embedded templates.
> \* TODO(bep) complete this.
> 
> \## Example layouts directory
> 
> \`\`\`
> layouts
> ├── baseof.html
> ├── home.html
> ├── list.html
> ├── single.html
> ├── taxonomy.html
> ├── term.html
> ├── term.mylayout.section.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
> \`\`\`
> 
> Fixes #13515
> Updates #7964
> Updates #13365
> Updates #12988
> Updates #4891
> 
> 
> 
> \## Fix/adjusment tasks
> 
> \- \[x\] Fix output format resolve issue in \`head/css.html\` and similar partials.
> \- \[x\] --printWarnings vs https://github.com/gohugoio/hugo/issues/13515.
> \- \[x\] TestLayoutAllRevised

> <https://github.com/gohugoio/hugoDocs/commit/5df1229d5fc4e06997c2186429d9c62fab783380>

> **[hugoDocs/layouts at 5df1229d5fc4e06997c2186429d9c62fab783380 · gohugoio/hugoDocs](https://github.com/gohugoio/hugoDocs/tree/5df1229d5fc4e06997c2186429d9c62fab783380/layouts)**
>
> The source for https://gohugo.io/. Contribute to gohugoio/hugoDocs development by creating an account on GitHub.

I tried making [hugo-theme-yue](https://github.com/CyrusYip/hugo-theme-yue) adapt to the new template system.

I renamed some directories and changed `{{ template "_internal/foo.html" . }}` to `{{- partial "foo.html" . }}`.

Original directories:

```auto
layouts
├── 404.html
├── _default
│ ├── baseof.html
│ ├── home.html
│ ├── list.html
│ ├── _markup
│ ├── rss.xml
│ └── single.html
└── partials
    ├── body
    ├── footer
    ├── footer.html
    ├── head
    ├── header
    ├── header.html
    ├── head.html
    ├── main
    └── single

```

Current directories:

```auto
layouts
├── 404.html
├── baseof.html
├── home.html
├── list.html
├── _markup
│ ├── render-heading.html
│ └── render-table.html
├── _partials
│ ├── body
│ ├── footer
│ ├── footer.html
│ ├── head
│ ├── header
│ ├── header.html
│ ├── head.html
│ ├── main
│ └── single
├── rss.xml
└── single.html

```

This is the commit that made changes:

> <https://github.com/CyrusYip/hugo-theme-yue/commit/1b24dde2c543a575810c2200f116f9a3acfd2170>

Are these changes enough?

---

<div class="post-metadata">

**Author:** ![frjo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/frjo/32/18626_2.png) [@frjo](https://discourse.gohugo.io/u/frjo)\
**Post date:** [May 9, 2025, 7:11am UTC](https://discourse.gohugo.io/t/how-to-adapt-to-the-new-template-system-introduced-in-hugo-0-146-0/54683/2 "2025-05-09T07:11:48Z")

</div>

Looks very much like what I did for v5 of my Zen theme [hugo-theme-zen/layouts at main · frjo/hugo-theme-zen · GitHub](https://github.com/frjo/hugo-theme-zen/tree/main/layouts)

I like the new layout structure, feels better organised.

---

<div class="post-metadata">

**Author:** ![tyco](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/tyco/32/23754_2.png) [@tyco](https://discourse.gohugo.io/u/tyco)\
**Post date:** [May 9, 2025, 7:15am UTC](https://discourse.gohugo.io/t/how-to-adapt-to-the-new-template-system-introduced-in-hugo-0-146-0/54683/3 "2025-05-09T07:15:25Z")

</div>

~~The file `single.html` is renamed to `page.html`.~~  
Both work.

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [May 9, 2025, 2:59pm UTC](https://discourse.gohugo.io/t/how-to-adapt-to-the-new-template-system-introduced-in-hugo-0-146-0/54683/4 "2025-05-09T14:59:35Z")

</div>

Also see [New template system in Hugo v0.146.0](https://gohugo.io/templates/new-templatesystem-overview/)

---

<div class="post-metadata">

**Author:** ![system](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/system/32/1_2.png) [@system](https://discourse.gohugo.io/u/system)\
**Post date:** [May 11, 2025, 3:00pm UTC](https://discourse.gohugo.io/t/how-to-adapt-to-the-new-template-system-introduced-in-hugo-0-146-0/54683/5 "2025-05-11T15:00:28Z")

</div>

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.