diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2024-01-27 10:47:28 +0100 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2024-01-27 10:47:28 +0100 |
commit | fc7de7136acbcf0aef54ae8460c7702bc83709be (patch) | |
tree | c109bb4dd1f1b054db476e7e4117f79bdd62ec9e /docs/content/en/content-management/build-options.md | |
parent | 1083bf7c08e6f35826279065b8a09a16cc991c7f (diff) |
docs: Prepare for new sub tree
See #11925
Diffstat (limited to 'docs/content/en/content-management/build-options.md')
-rw-r--r-- | docs/content/en/content-management/build-options.md | 321 |
1 files changed, 0 insertions, 321 deletions
diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md deleted file mode 100644 index bc9d7ff49..000000000 --- a/docs/content/en/content-management/build-options.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -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] -menu: - docs: - parent: content-management - weight: 70 -weight: 70 -toc: true -aliases: [/content/build-options/] ---- - -Build options are stored in a reserved front matter object named `_build` with these defaults: - -{{< code-toggle file=content/example/index.md fm=true >}} -[_build] -list = 'always' -publishResources = true -render = 'always' -{{< /code-toggle >}} - - -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. - - - `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` - : Do not include the page in _any_ page collection. - -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 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 %}} - -## 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 - -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 >}} -{{ with .Site.GetPage "/headless" }} - {{ range .Pages }} - {{ .Content }} - {{ range .Resources.ByType "image" }} - <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> - {{ end }} - {{ end }} -{{ end }} -{{< /code >}} - -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 - -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 >}} - -To render the glossary: - -{{< code file=layouts/glossary/list.html >}} -<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 -``` |