Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

26 files changed, 615 insertions, 391 deletions

diff --git a/docs/content/en/content-management/_common/_index.md b/docs/content/en/content-management/_common/_index.md
new file mode 100644
index 000000000..47d5812fb
--- /dev/null
+++ b/docs/content/en/content-management/_common/_index.md
@@ -0,0 +1,13 @@
+---
+cascade:
+  _build:
+    list: never
+    publishResources: false
+    render: never
+---
+
+<!--
+Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode. 
+-->
diff --git a/docs/content/en/content-management/_common/page-kinds.md b/docs/content/en/content-management/_common/page-kinds.md
new file mode 100644
index 000000000..07a53e8e6
--- /dev/null
+++ b/docs/content/en/content-management/_common/page-kinds.md
@@ -0,0 +1,17 @@
+---
+# Do not remove front matter.
+---
+
+| Kind | Description | Example |
+|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------|
+| `home` | The landing page for the home page | `/index.html` |
+| `page` | The landing page for a given page | `my-post` page (`/posts/my-post/index.html`) |
+| `section` | The landing page of a given section | `posts` section (`/posts/index.html`) |
+| `taxonomy` | The landing page for a taxonomy | `tags` taxonomy (`/tags/index.html`) |
+| `term` | The landing page for one taxonomy's term | term `awesome` in `tags` taxonomy (`/tags/awesome/index.html`) |
+
+Four other page kinds unrelated to content are `robotsTXT`, `RSS`, `sitemap`, and `404`. Although primarily for internal use, you can specify the name when disabling one or more page kinds on your site. For example:
+
+{{< code-toggle file=hugo >}}
+disableKinds = ['robotsTXT','404']
+{{< /code-toggle >}}
diff --git a/docs/content/en/content-management/_index.md b/docs/content/en/content-management/_index.md
index 35f85a641..66af24681 100644
--- a/docs/content/en/content-management/_index.md
+++ b/docs/content/en/content-management/_index.md
@@ -2,13 +2,13 @@
 title: Content management
 linkTitle: Overview
 description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more.
+categories: []
+keywords: []
 menu:
   docs:
     identifier: content-management-overview
     parent: content-management
     weight: 10
-keywords: [source, organization]
-categories: [content management]
 weight: 10
 aliases: [/content/,/content/organization]
 ---
diff --git a/docs/content/en/content-management/archetypes.md b/docs/content/en/content-management/archetypes.md
index fe460f91f..94f038848 100644
--- a/docs/content/en/content-management/archetypes.md
+++ b/docs/content/en/content-management/archetypes.md
@@ -1,15 +1,15 @@
 ---
 title: Archetypes
 description: An archetype is a template for new content.
-keywords: [archetypes,generators,metadata,front matter]
 categories: [content management]
+keywords: [archetypes,generators,metadata,front matter]
 menu:
   docs:
     parent: content-management
     weight: 140
   quicklinks:
-toc: true
 weight: 140
+toc: true
 aliases: [/content/archetypes/]
 ---
 
@@ -19,7 +19,7 @@ A content file consists of [front matter] and markup. The markup is typically ma
 
 The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype:
 
-{{< code-toggle file="archetypes/default.md" copy=false fm=true >}}
+{{< code-toggle file=archetypes/default.md fm=true >}}
 title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
 date = '{{ .Date }}'
 draft = true
@@ -27,13 +27,13 @@ draft = true
 
 When you create new content, Hugo evaluates the [template actions] within the archetype. For example:
 
-```text
+```sh
 hugo new content posts/my-first-post.md
 ```
 
 With the default archetype shown above, Hugo creates this content file:
 
-{{< code-toggle file="content/posts/my-first-post.md" copy=false fm=true >}}
+{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
 title = 'My First Post'
 date = '2023-08-24T11:49:46-07:00'
 draft = true
@@ -53,7 +53,7 @@ Hugo looks for archetypes in the `archetypes` directory in the root of your proj
 
 For example, with this command:
 
-```text
+```sh
 hugo new content posts/my-first-post.md
 ```
 
@@ -75,7 +75,7 @@ Archetypes receive the following objects and values in [context]:
 - `.Date`
 - `.Type`
 - `.Site` (see [details](/variables/site/))
-- `.File` (see [details](/variables/files/))
+- `.File` (see [details](/variables/file/))
 
 As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter.
 
@@ -85,8 +85,7 @@ Although typically used as a front matter template, you can also use an archetyp
 
 For example, in a documentation site you might have a section (content type) for functions. Every page within this section should follow the same format: a brief description, the function signature, examples, and notes. We can pre-populate the page to remind content authors of the standard format.
 
-
-{{< code file="archetypes/functions.md" copy=false >}}
+{{< code file=archetypes/functions.md >}}
 ---
 date: '{{ .Date }}'
 draft: true
@@ -125,17 +124,17 @@ Create an archetype for galleries:
 ```text
 archetypes/
 ├── galleries/
-│   ├── images/
-│   │   └── .gitkeep
-│   └── index.md      <-- same format as default.md
+│   ├── images/
+│   │   └── .gitkeep
+│   └── index.md      <-- same format as default.md
 └── default.md
 ```
 
 Subdirectories within an archetype must contain at least one file. Without a file, Hugo will not create the subdirectory when you create new content. The name and size of the file are irrelevant. The example above includes a&nbsp;`.gitkeep` file, an empty file commonly used to preserve otherwise empty directories in a Git repository.
 
-
 To create a new gallery:
-```text
+
+```sh
 hugo new galleries/bryce-canyon
 ```
 
@@ -166,13 +165,13 @@ archetypes/
 
 To create an article using the articles archetype:
 
-```text
+```sh
 hugo new content articles/something.md
 ```
 
 To create an article using the tutorials archetype:
 
-```text
+```sh
 hugo new content --kind tutorials articles/something.md
 ```
 
diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md
index 378a31144..bc9d7ff49 100644
--- a/docs/content/en/content-management/build-options.md
+++ b/docs/content/en/content-management/build-options.md
@@ -1,102 +1,321 @@
 ---
 title: Build options
 description: Build options help define how Hugo must treat a given page when building the site.
+categories: [content management,fundamentals]
 keywords: [build,content,front matter, page resources]
-categories: [fundamentals,content management]
 menu:
   docs:
     parent: content-management
     weight: 70
-toc: true
 weight: 70
+toc: true
 aliases: [/content/build-options/]
 ---
 
-They are stored in a reserved front matter object named `_build` with the following defaults:
+Build options are stored in a reserved front matter object named `_build` with these defaults:
 
-{{< code-toggle >}}
-_build:
-  render: always
-  list: always
-  publishResources: true
+{{< code-toggle file=content/example/index.md fm=true >}}
+[_build]
+list = 'always'
+publishResources = true
+render = 'always'
 {{< /code-toggle >}}
 
-#### render
 
-If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink.
+list
+: When to include the page within page collections. Specify one of:
+  
+  - `always`
+    : Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value.
 
-Valid values are:
+  - `local`
+    : Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections.
 
   - `never`
-    : The page will not be included in any page collection.
-  - `always (default)`
-    : The page will be rendered to disk and get a `RelPermalink` etc.
-  - `link`
-    : The page will be not be rendered to disk, but will get a `RelPermalink`.
+    : Do not include the page in _any_ page collection.
 
-#### list
+publishResources
+: Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of:
 
-Valid values are:
-  
-  - `never`
-    : The page will not be included in any page collection.
-  - `always (default)`
-    : The page will be included in all page collections, e.g. `site.RegularPages`, `.Pages`.
-  - `local`
-    : The page will be included in any _local_ page collection, e.g. `.RegularPages`, `.Pages`. One use case for this would be to create fully navigable, but headless content sections.
+  - `true`
+    : Always publish resources. This is the default value.
 
-#### publishResources
+  - `false`
+    : Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template.
 
-If set to `true` (default) the [Bundle's Resources](/content-management/page-bundles) will be published.
-Setting this to `false` will still publish Resources on demand (when a resource's `.Permalink` or `.RelPermalink` is invoked from the templates) but will skip the others.
+render
+: When to render the page. Specify one of:
+
+  - `always`
+    : Always render the page to disk. This is the default value.
+
+  - `link`
+    : Do not render the page to disk, but include it in all page collections.
+
+  - `never`
+    : Never render the page to disk, and exclude it from all page collections.
+
+[page bundles]: content-management/page-bundles
+[page resources]: /content-management/page-resources
+[`Permalink`]: /methods/resource/permalink
+[`RelPermalink`]: /methods/resource/relpermalink
+[`Publish`]: /methods/resource/publish
 
 {{% note %}}
-Any page, regardless of their build options, will always be available using the [`.GetPage`](/functions/getpage) methods.
+Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method.
+
+[`.Page.GetPage`]: /methods/page/getpage
+[`.Site.GetPage`]: /methods/site/getpage
 {{% /note %}}
 
-### Illustrative use cases
+## Example -- headless page
+
+Create a unpublished page whose content and resources can be included in other pages.
+
+```text
+content/
+├── headless/
+│   ├── a.jpg
+│   ├── b.jpg
+│   └── index.md  <-- leaf bundle
+└── _index.md     <-- home page
+```
+
+Set the build options in front matter:
+
+{{< code-toggle file=content/headless/index.md fm=true >}}
+title = 'Headless page'
+[_build]
+  list = 'never'
+  publishResources = false
+  render = 'never'
+{{< /code-toggle >}}
+
+To include the content and images on the home page:
+
+{{< code file=layouts/_default/home.html  >}}
+{{ with .Site.GetPage "/headless" }}
+  {{ .Content }}
+  {{ range .Resources.ByType "image" }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ end }}
+{{ end }}
+{{< /code >}}
+
+The published site will have this structure:
+
+```text
+public/
+├── headless/
+│   ├── a.jpg
+│   └── b.jpg
+└── index.html
+```
+
+In the example above, note that:
+
+1. Hugo did not publish an HTML file for the page.
+2. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
+
+## Example -- headless section
 
-#### Not publishing a page
+Create a unpublished section whose content and resources can be included in other pages.
 
-Project needs a "Who We Are" content file for front matter and body to be used by the homepage but nowhere else.
+[branch bundle]: /content-management/page-bundles
 
-{{< code-toggle file="content/who-we-are.md" fm=true copy=false >}}
-title: Who we are
-_build:
- list: false
- render: false
+```text
+content/
+├── headless/
+│   ├── note-1/
+│   │   ├── a.jpg
+│   │   ├── b.jpg
+│   │   └── index.md  <-- leaf bundle
+│   ├── note-2/
+│   │   ├── c.jpg
+│   │   ├── d.jpg
+│   │   └── index.md  <-- leaf bundle
+│   └── _index.md     <-- branch bundle
+└── _index.md         <-- home page
+```
+
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
+
+{{< code-toggle file=content/headless/_index.md fm=true >}}
+title = 'Headless section'
+[[cascade]]
+[cascade._build]
+  list = 'local'
+  publishResources = false
+  render = 'never'
 {{< /code-toggle >}}
 
-{{< code file="layouts/index.html" copy=false >}}
-<section id="who-we-are">
-  {{ with site.GetPage "who-we-are" }}
+In the front matter above, note that we have set `list` to `local` to include the descendant pages in local page collections.
+
+To include the content and images on the home page:
+
+{{< code file=layouts/_default/home.html  >}}
+{{ with .Site.GetPage "/headless" }}
+  {{ range .Pages }}
     {{ .Content }}
+    {{ range .Resources.ByType "image" }}
+      <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+    {{ end }}
   {{ end }}
-</section>
+{{ end }}
 {{< /code >}}
 
-#### Listing pages without publishing them
+The published site will have this structure:
+
+```text
+public/
+├── headless/
+│   ├── note-1/
+│   │   ├── a.jpg
+│   │   └── b.jpg
+│   └── note-2/
+│       ├── c.jpg
+│       └── d.jpg
+└── index.html
+```
+
+In the example above, note that:
+
+1. Hugo did not publish an HTML file for the page.
+2. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
+
+## Example -- list without publishing
 
-Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them.
+Publish a section page without publishing the descendant pages. For example, to create a glossary:
 
-To avoid setting the build options on every testimonials, one can use [`cascade`](/content-management/front-matter#front-matter-cascade) on the testimonial section's content file.
+```text
+content/
+├── glossary/
+│   ├── _index.md
+│   ├── bar.md
+│   ├── baz.md
+│   └── foo.md
+└── _index.md
+```
 
-{{< code-toggle >}}
-title: Testimonials
-_build:
-  render: true
-cascade:
-  _build:
-    render: false
-    list: true # default
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
+
+{{< code-toggle file=content/glossary/_index.md fm=true >}}
+title = 'Glossary'
+[_build]
+render = 'always'
+[[cascade]]
+[cascade._build]
+  list = 'local'
+  publishResources = false
+  render = 'never'
 {{< /code-toggle >}}
 
-{{< code file="layouts/_defaults/testimonials.html" copy=false >}}
-<section id="testimonials">
-  {{ range first 5 .Pages }}
-    <blockquote cite="{{ .Params.cite }}">
-      {{ .Content }}
-    </blockquote>
+To render the glossary:
+
+{{< code file=layouts/glossary/list.html  >}}
+<dl>
+  {{ range .Pages }}
+    <dt>{{ .Title }}</dt>
+    <dd>{{ .Content }}</dd>
   {{ end }}
-</section>
+</dl>
 {{< /code >}}
+
+The published site will have this structure:
+
+```text
+public/
+├── glossary/
+│   └── index.html
+└── index.html
+```
+
+## Example -- publish without listing
+
+Publish a section's descendant pages without publishing the section page itself.
+
+```text
+content/
+├── books/
+│   ├── _index.md
+│   ├── book-1.md
+│   └── book-2.md
+└── _index.md
+```
+
+Set the build options in front matter:
+
+{{< code-toggle file=content/books/_index.md >}}
+title = 'Books'
+[_build]
+render = 'never'
+list = 'never'
+{{< /code-toggle >}}
+
+The published site will have this structure:
+
+```html
+public/
+├── books/
+│   ├── book-1/
+│   │   └── index.html
+│   └── book-2/
+│       └── index.html
+└── index.html
+```
+
+## Example -- conditionally hide section
+
+Consider this example. A documentation site has a team of contributors with access to 20 custom shortcodes. Each shortcode takes several arguments, and requires documentation for the contributors to reference when using them.
+
+Instead of external documentation for the shortcodes, include an "internal" section that is hidden when building the production site.
+
+```text
+content/
+├── internal/
+│   ├── shortcodes/
+│   │   ├── _index.md
+│   │   ├── shortcode-1.md
+│   │   └── shortcode-2.md
+│   └── _index.md
+├── reference/
+│   ├── _index.md
+│   ├── reference-1.md
+│   └── reference-2.md
+├── tutorials/
+│   ├── _index.md
+│   ├── tutorial-1.md
+│   └── tutorial-2.md
+└── _index.md
+```
+
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages, and use the `target` keyword to target the production environment.
+
+{{< code-toggle file=content/internal/_index.md >}}
+title = 'Internal'
+[[cascade]]
+[cascade._build]
+render = 'never'
+list = 'never'
+[cascade._target]
+environment = 'production'
+{{< /code-toggle >}}
+
+The production site will have this structure:
+
+```html
+public/
+├── reference/
+│   ├── reference-1/
+│   │   └── index.html
+│   ├── reference-2/
+│   │   └── index.html
+│   └── index.html
+├── tutorials/
+│   ├── tutorial-1/
+│   │   └── index.html
+│   ├── tutorial-2/
+│   │   └── index.html
+│   └── index.html
+└── index.html
+```
diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md
index 39663013b..9985dd1e6 100644
--- a/docs/content/en/content-management/comments.md
+++ b/docs/content/en/content-management/comments.md
@@ -1,14 +1,14 @@
 ---
 title: Comments
 description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
+categories: [content management]
 keywords: [sections,content,organization]
-categories: [project organization]
 menu:
   docs:
     parent: content-management
     weight: 220
-toc: true
 weight: 220
+toc: true
 aliases: [/extras/comments/]
 ---
 
diff --git a/docs/content/en/content-management/cross-references.md b/docs/content/en/content-management/cross-references.md
index c989cc560..500e388a4 100644
--- a/docs/content/en/content-management/cross-references.md
+++ b/docs/content/en/content-management/cross-references.md
@@ -2,13 +2,13 @@
 title: Links and cross references
 description: Shortcodes for creating links to documents.
 categories: [content management]
-keywords: ["cross references","references", "anchors", "urls"]
+keywords: [cross references,references,anchors,urls]
 menu:
   docs:
     parent: content-management
     weight: 170
-toc: true
 weight: 170
+toc: true
 aliases: [/extras/crossreferences/]
 ---
 
@@ -35,7 +35,6 @@ The `ref` and `relref` shortcodes require a single parameter: the path to a cont
 
 The pages can be referenced as follows:
 
-
 ```text
 {{</* ref "document2" */>}}             // <- From pages/document1.md, relative path
 {{</* ref "document2#anchor" */>}}      
@@ -138,7 +137,7 @@ produces this HTML:
 
 ## Ref and RelRef Configuration
 
-The behavior can, since Hugo 0.45, be configured in `hugo.toml`:
+The behavior can be configured in `hugo.toml`:
 
 refLinksErrorLevel ("ERROR")
 : When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
@@ -146,7 +145,6 @@ refLinksErrorLevel ("ERROR")
 refLinksNotFoundURL
 : URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
 
-
 [lists]: /templates/lists/
 [output formats]: /templates/output-formats/
 [shortcode]: /content-management/shortcodes/
diff --git a/docs/content/en/content-management/diagrams.md b/docs/content/en/content-management/diagrams.md
index c0b2349b0..17407098f 100644
--- a/docs/content/en/content-management/diagrams.md
+++ b/docs/content/en/content-management/diagrams.md
@@ -7,12 +7,12 @@ menu:
   docs:
     parent: content-management
     weight: 50
-toc: true
 weight: 50
+toc: true
 ---
-{{< new-in "0.93.0" >}}
+{{< new-in 0.93.0 >}}
 
-## GoAT diagrams (Ascii)
+## GoAT diagrams (ASCII)
 
 Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
 
@@ -165,7 +165,6 @@ Created from <https://arthursonzogni.com/Diagon