diff --git a/content/en/templates/base.md b/content/en/templates/base.md
index bb6a25b1e..966dcfd06 100644
--- a/content/en/templates/base.md
+++ b/content/en/templates/base.md
@@ -7,6 +7,8 @@ weight: 40
 aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
 ---
 
+{{< newtemplatesystem >}}
+
 The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary.
 
 {{< youtube QVOMCYitLEc >}}
diff --git a/content/en/templates/content-view.md b/content/en/templates/content-view.md
index f001e400e..ef214d07f 100644
--- a/content/en/templates/content-view.md
+++ b/content/en/templates/content-view.md
@@ -7,6 +7,8 @@ weight: 110
 aliases: [/templates/views/]
 ---
 
+{{< newtemplatesystem >}}
+
 The following are common use cases for content views:
 
 - You want content of every type to be shown on the home page but only with limited [summary views][summaries].
diff --git a/content/en/templates/embedded.md b/content/en/templates/embedded.md
index ecfd90514..99d3b0c69 100644
--- a/content/en/templates/embedded.md
+++ b/content/en/templates/embedded.md
@@ -7,6 +7,8 @@ weight: 170
 aliases: [/templates/internal]
 ---
 
+{{< newtemplatesystem >}}
+
 ## Disqus
 
 > [!note]
diff --git a/content/en/templates/home.md b/content/en/templates/home.md
index 937a4a5a8..08faae1ab 100644
--- a/content/en/templates/home.md
+++ b/content/en/templates/home.md
@@ -7,6 +7,9 @@ weight: 50
 aliases: [/layout/homepage/,/templates/homepage-template/,/templates/homepage/]
 ---
 
+{{< newtemplatesystem >}}
+
+
 ## Introduction
 
 A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages.
diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md
index a5b33223a..5c52dbea3 100644
--- a/content/en/templates/introduction.md
+++ b/content/en/templates/introduction.md
@@ -7,6 +7,9 @@ keywords: []
 weight: 10
 ---
 
+{{< newtemplatesystem >}}
+
+
 {{% glossary-term template %}}
 
 Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page.
diff --git a/content/en/templates/lookup-order.md b/content/en/templates/lookup-order.md
index 518900797..802c6a65b 100644
--- a/content/en/templates/lookup-order.md
+++ b/content/en/templates/lookup-order.md
@@ -7,6 +7,8 @@ keywords: []
 weight: 20
 ---
 
+{{< newtemplatesystem >}}
+
 ## Lookup rules
 
 Hugo takes the parameters listed below into consideration when choosing a template for a given page. The templates are ordered by specificity. This should feel natural, but look at the table below for concrete examples of the different parameter variations.
diff --git a/content/en/templates/new-templatesystem-overview.md b/content/en/templates/new-templatesystem-overview.md
new file mode 100644
index 000000000..9a6f00d85
--- /dev/null
+++ b/content/en/templates/new-templatesystem-overview.md
@@ -0,0 +1,99 @@
+
+---
+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` folder anymore, unless this represents a [Page path].|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`), 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] 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 shortcodes, render hooks, partials, and page templates. The previous setup was very hard 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] 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
+
+```
+layouts
+├── baseof.html
+├── baseof.term.html
+├── home.html
+├── list.html
+├── single.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
+│       ├── 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/
+[Example folder structure]: #example-folder-structure
+
+[^type]: The `type` set in front matter will effectively replace the `section` folder in [Page path] when doing lookups.
+[^internal]: The old way of doing it made it very hard/impossible to, e.g., override `_internal/disqus.html` in a theme. Now you can just create a partial with the same name.
+
diff --git a/content/en/templates/section.md b/content/en/templates/section.md
index 8bc0f9dab..65e1019c1 100644
--- a/content/en/templates/section.md
+++ b/content/en/templates/section.md
@@ -7,6 +7,9 @@ weight: 70
 aliases: [/templates/sections/,/templates/section-templates/]
 ---
 
+{{< newtemplatesystem >}}
+
+
 ## Add content and front matter to section templates
 
 To effectively leverage section templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages.
diff --git a/content/en/templates/shortcode.md b/content/en/templates/shortcode.md
index 3ed573651..5efb59120 100644
--- a/content/en/templates/shortcode.md
+++ b/content/en/templates/shortcode.md
@@ -7,6 +7,9 @@ weight: 120
 aliases: [/templates/shortcode-templates/]
 ---
 
+{{< newtemplatesystem >}}
+
+
 > [!note]
 > Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates.
 
diff --git a/content/en/templates/single.md b/content/en/templates/single.md
index 6f244ef10..727f596af 100644
--- a/content/en/templates/single.md
+++ b/content/en/templates/single.md
@@ -7,6 +7,9 @@ weight: 60
 aliases: [/layout/content/,/templates/single-page-templates/]
 ---
 
+{{< newtemplatesystem >}}
+
+
 The single template below inherits the site's shell from the [base template].
 
 [base template]: /templates/types/
diff --git a/content/en/templates/taxonomy.md b/content/en/templates/taxonomy.md
index 96c93ec95..b698a8cd5 100644
--- a/content/en/templates/taxonomy.md
+++ b/content/en/templates/taxonomy.md
@@ -7,6 +7,9 @@ weight: 80
 aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy-templates/]
 ---
 
+{{< newtemplatesystem >}}
+
+
 The [taxonomy](g) template below inherits the site's shell from the [base template], and renders a list of [terms](g) in the current taxonomy.
 
 [base template]: /templates/types/
diff --git a/content/en/templates/term.md b/content/en/templates/term.md
index cf1097e86..6c29c67f7 100644
--- a/content/en/templates/term.md
+++ b/content/en/templates/term.md
@@ -6,6 +6,9 @@ keywords: []
 weight: 90
 ---
 
+{{< newtemplatesystem >}}
+
+
 The [term](g) template below inherits the site's shell from the [base template], and renders a list of pages associated with the current term.
 
 [base template]: /templates/types/
diff --git a/content/en/templates/types.md b/content/en/templates/types.md
index b44d3eb47..b7bc3f763 100644
--- a/content/en/templates/types.md
+++ b/content/en/templates/types.md
@@ -7,6 +7,9 @@ weight: 30
 aliases: ['/templates/lists/']
 ---
 
+{{< newtemplatesystem >}}
+
+
 ## Structure
 
 Create templates in the `layouts` directory in the root of your project.
diff --git a/layouts/_shortcodes/newtemplatesystem.html b/layouts/_shortcodes/newtemplatesystem.html
new file mode 100644
index 000000000..0bebcd622
--- /dev/null
+++ b/layouts/_shortcodes/newtemplatesystem.html
@@ -0,0 +1,12 @@
+{{ $text := `We did a complete overhaul of Hugo's template system in v0.146.0.
+  We're working on getting all of the relevant documentation up to date, but until
+  then, see [this page](/templates/new-templatesystem-overview/). `
+}}
+{{ partial "layouts/blocks/alert.html"
+  (dict
+  "color"  "orange"
+  "icon"  "information-circle"
+  "text" ($text | $.Page.RenderString )
+  "title" ""
+  "class" "text-black")
+}}