mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-30 22:39:58 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-12-04 15:24:01 +01:00
parent 9f978d387f 35dec7c96f
commit d19ed4d4e6
810 changed files with 24147 additions and 7766 deletions
Download Patch File Download Diff File Expand all files Collapse all files

343
docs/content/en/content-management/build-options.md
View File

@@ -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.
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`](/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
#### 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 copy=false >}}
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" copy=false >}}
<section id="who-we-are">
{{ with site.GetPage "who-we-are" }}
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 }}
</section>
{{ 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" 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
```