Add a one pager about the new template system

Author: bep

content/en/templates/new-templatesystem-overview.md

@@ -0,0 +1,88 @@
+
+---
+title: New template system in Hugo v0.146.0
+description: Overview of the new template system in Hugo v0.146.0
+categories: []
+keywords: []
+weight: 1
+---
+
+
+In [Hugo v0.146.0] we did a full re-implementation of how we handle Go templates in Hugo. This included some structural changes to the `layouts` folder and a new and more powerful template lookup system.
+
+We have strived to be as backwards compatible as possible. We're working on a full overhaul of the documentation about 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 not starts 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.|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`) you could prepended one identifier (layout, type or kind) with a hyphen in front of the baseof keyword.|Move that identifier after the first "dot", e.g. `list-baseof.html` => `baseof.list.html`|
+|We have added a new `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.||
+|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 a `index.html` template for the home page anymore. | Rename `index.html` to `home.html`|
+
+
+## Changes template lookup order
+
+We have consolidated the template lookup so it should work the same across all of shortcodes, render hooks, partials, and page templates. What we had before was very hard to understand and had a massive amount of variants. What we have aimed for with the new setup is something that should feel natural with few surprises.
+
+The identifiers used in the template weighting, in approximate order of importance, are:
+
+| Identifier | Description |
+| ---------- | ----------- |
+| Custom layout | The custom `layout` set in front matter |
+| [Page kinds] | The page kind (`home`, `section`, `taxonomy`, `term`, `page`) |
+| Standard layouts 1 |`list` and `single`|
+| Output format | The output format (e.g. `html`, `rss`) |
+| Standard layouts 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 | If `type` is set in front matter, the value of `type` will replace the top level section in the Page path above.|
+
+For templates placed in the [Page path], a closer match will be considered _better_. In the example folder 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 to render the base template for the Page path `/docs` and below.
+
+```
+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
+
+
+[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/