diff --git a/content/en/content-management/build-options.md b/content/en/content-management/build-options.md
index 2fddcedd7..918635cfc 100644
--- a/content/en/content-management/build-options.md
+++ b/content/en/content-management/build-options.md
@@ -12,112 +12,310 @@ 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.
-
-Valid values are:
-
- - `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`.
-
-#### list
-
-Valid values are:
+list
+: When to include the page within page collections. Specify one of:
- - `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`.
+ - `always`
+ : Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value.
+
- `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.
+ : Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections.
-#### publishResources
+ - `never`
+ : Do not include the page in _any_ page collection.
-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.
+publishResources
+: Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of:
+
+ - `true`
+ : Always publish resources. This is the default value.
+
+ - `false`
+ : Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template.
+
+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`](/methods/page/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
-#### Not publishing a page
+Create a unpublished page 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.
+```text
+content/
+├── headless/
+│ ├── a.jpg
+│ ├── b.jpg
+│ └── index.md <-- leaf bundle
+└── _index.md <-- home page
+```
-{{< code-toggle file="content/who-we-are.md" fm=true >}}
-title: Who we are
-_build:
- list: false
- render: false
+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 >}}
-{{< code file="layouts/index.html" >}}
-
- {{ with site.GetPage "who-we-are" }}
+To include the content and images on the home page:
+
+{{< code file="layouts/_default/home.html" lang=go-html-template >}}
+{{ with .Site.GetPage "/headless" }}
+ {{ .Content }}
+ {{ range .Resources.ByType "image" }}
+ 
+ {{ 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
+
+Create a unpublished section whose content and resources can be included in other pages.
+
+[branch bundle]: /content-management/page-bundles
+
+```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 >}}
+
+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" lang=go-html-template >}}
+{{ with .Site.GetPage "/headless" }}
+ {{ range .Pages }}
{{ .Content }}
+ {{ range .Resources.ByType "image" }}
+
+ {{ end }}
{{ end }}
-
+{{ end }}
{{< /code >}}
-#### Listing pages without publishing them
+The published site will have this structure:
-Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them.
+```text
+public/
+├── headless/
+│ ├── note-1/
+│ │ ├── a.jpg
+│ │ └── b.jpg
+│ └── note-2/
+│ ├── c.jpg
+│ └── d.jpg
+└── index.html
+```
-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.
+In the example above, note that:
-{{< code-toggle >}}
-title: Testimonials
-_build:
- render: true
-cascade:
- _build:
- render: false
- list: true # default
+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
+
+Publish a section page without publishing the descendant pages. For example, to create a glossary:
+
+```text
+content/
+├── glossary/
+│ ├── _index.md
+│ ├── bar.md
+│ ├── baz.md
+│ └── foo.md
+└── _index.md
+```
+
+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" >}}
-
- {{ range first 5 .Pages }}
-
- {{ .Content }}
-
+To render the glossary:
+
+{{< code file=layouts/glossary/list.html lang=go-html-template >}}
+
+ {{ range .Pages }}
+ - {{ .Title }}
+ - {{ .Content }}
{{ end }}
-
+
{{< /code >}}
-#### Not rendering an index file for a hidden section
+The published site will have this structure:
-Website wants to hide a section from sitemap, menu and other navigation, but still wants to have all children rendered.
+```text
+public/
+├── glossary/
+│ └── index.html
+└── index.html
+```
-See the forum question: [Disable generating empty index.html pages created for sections](https://discourse.gohugo.io/t/disable-generating-empty-index-html-pages-created-for-sections/11036/1)
+## Example -- publish without listing
-This use case leverages [`cascade`](/content-management/front-matter#front-matter-cascade) as well.
+Publish a section's descendant pages without publishing the section page itself.
-{{< code-toggle >}}
-title: Section without index file
-url: /hidden-section/
-_build:
- render: never
- list: never
- publishResources: false
-cascade:
- _build:
- list: false
- render: true
+```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
+```