Clean up build option descriptions and examples

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 >}}
+{{< code-toggle file="content/example/index.md" fm=true >}}
-_build:
+[_build]
-  render: always
+list = 'always'
-  list: always
+publishResources = true
-  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:
   
-Valid values are:
+  - `always`
+    : Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value.
 
-  - `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:
-  
-  - `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.
+    : 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.
+publishResources
-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.
+: 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 >}}
+Set the build options in front matter:
-title: Who we are
+
-_build:
+{{< code-toggle file=content/headless/index.md fm=true >}}
- list: false
+title = 'Headless page'
- render: false
+[_build]
+  list = 'never'
+  publishResources = false
+  render = 'never'
 {{< /code-toggle >}}
 
-{{< code file="layouts/index.html" >}}
+To include the content and images on the home page:
-<section id="who-we-are">
+
-  {{ with site.GetPage "who-we-are" }}
+{{< code file="layouts/_default/home.html" lang=go-html-template >}}
+{{ with .Site.GetPage "/headless" }}
   {{ .Content }}
+  {{ range .Resources.ByType "image" }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ end }}
 {{ end }}
-</section>
 {{< /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/
+│   ├── a.jpg
+│   └── b.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 >}}
+1. Hugo did not publish an HTML file for the page.
-title: Testimonials
+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.
-_build:
+
-  render: true
+## Example -- headless section
-cascade:
+
-  _build:
+Create a unpublished section whose content and resources can be included in other pages.
-    render: false
+
-    list: true # default
+[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 >}}
 
-{{< code file="layouts/_defaults/testimonials.html" >}}
+In the front matter above, note that we have set `list` to `local` to include the descendant pages in local page collections.
-<section id="testimonials">
+
-  {{ range first 5 .Pages }}
+To include the content and images on the home page:
-    <blockquote cite="{{ .Params.cite }}">
+
+{{< code file="layouts/_default/home.html" lang=go-html-template >}}
+{{ with .Site.GetPage "/headless" }}
+  {{ range .Pages }}
     {{ .Content }}
-    </blockquote>
+    {{ range .Resources.ByType "image" }}
+      <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+    {{ end }}
+  {{ end }}
 {{ end }}
-</section>
 {{< /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/
+├── headless/
+│   ├── note-1/
+│   │   ├── a.jpg
+│   │   └── b.jpg
+│   └── note-2/
+│       ├── c.jpg
+│       └── d.jpg
+└── 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)
+In the example above, note that:
 
-This use case leverages [`cascade`](/content-management/front-matter#front-matter-cascade) as well.
+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.
 
-{{< code-toggle >}}
+## Example -- list without publishing
-title: Section without index file
+
-url: /hidden-section/
+Publish a section page without publishing the descendant pages. For example, to create a glossary:
-_build:
+
-  render: never
+```text
-  list: never
+content/
-  publishResources: false
+├── glossary/
-cascade:
+│   ├── _index.md
-  _build:
+│   ├── bar.md
-    list: false
+│   ├── baz.md
-    render: true
+│   └── 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 >}}
+
+To render the glossary:
+
+{{< code file=layouts/glossary/list.html lang=go-html-template >}}
+<dl>
+  {{ range .Pages }}
+    <dt>{{ .Title }}</dt>
+    <dd>{{ .Content }}</dd>
+  {{ end }}
+</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
+```