From dff3c4abb808c24c507560d550e06eb74f07dc91 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Mon, 6 Nov 2023 12:26:11 -0800 Subject: [PATCH] Clean up build option descriptions and examples --- .../en/content-management/build-options.md | 348 ++++++++++++++---- 1 file changed, 273 insertions(+), 75 deletions(-) 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 +```