--- 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` or `layouts/section` folders anymore, unless it represents a [Page path][]. | Move them up to `layouts/` with one of the [Page kinds][] `section`, `taxonomy` or `term` as the base name, or place the layouts into the taxonomy [Page path][]. | | A template named `taxonomy.html` used to be a candidate for both Page kind `term` and `taxonomy`, now it's only considered for `taxonomy`. | Create both `taxonomy.html` and `term.html` or create a more general layout, e.g. `list.html`. | | 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](#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 [template types][]. The previous setup was difficult 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](#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 ```tree layouts ├── baseof.html ├── baseof.term.html ├── home.html ├── page.html ├── section.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 │ ├── page.html │ └── _markup │ └── render-link.html └── tags ├── taxonomy.html ├── term.html └── blue └── list.html ``` [^internal]: The old way of doing it made it difficult or impossible to, e.g., override `_internal/disqus.html` in a theme. Now you can just create a partial with the same name. [^type]: The `type` set in front matter will effectively replace the `section` folder in [Page path][] when doing lookups. [Hugo v0.146.0]: https://github.com/gohugoio/hugo/releases/tag/v0.146.0 [Page kinds]: https://gohugo.io/methods/page/kind/ [Page path]: https://gohugo.io/methods/page/path/ [template types]: /templates/types/