Build options
Build options are stored in a reserved front matter object named build with these defaults:
---
build:
list: always
publishResources: true
render: always
---+++
[build]
list = 'always'
publishResources = true
render = 'always'
+++{
"build": {
"list": "always",
"publishResources": true,
"render": "always"
}
}
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 a template calls itsPermalink,RelPermalink, orPublishmethod, or passes it to theresources.Publishfunction.
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 assignPermalinkandRelPermalinkvalues.never: Never render the page to disk, and exclude it from all page collections.
The Page.GetPage and Site.GetPage methods return any page, regardless of its build options.
Headless page
Create an unpublished page whose content and resources you can include in other pages. Consider this content structure:
content/
├── headless/
│ ├── a.jpg
│ ├── b.jpg
│ └── index.md <-- leaf bundle
└── _index.md <-- home pageSet the build options in front matter of the leaf bundle:
---
build:
list: never
publishResources: false
render: never
title: Headless page
---+++
title = 'Headless page'
[build]
list = 'never'
publishResources = false
render = 'never'
+++{
"build": {
"list": "never",
"publishResources": false,
"render": "never"
},
"title": "Headless page"
}
Use the Site.GetPage method in the home template to include the content and images on the home page:
{{ with site.GetPage "/headless" }}
{{ .Content }}
{{ range .Resources.ByType "image" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}When you build the project, the public directory has this structure:
public/
├── headless/
│ ├── a.jpg
│ └── b.jpg
└── index.htmlHugo does not publish an HTML file for the headless page. Hugo publishes the page resources even though publishResources is false, because the template calls the RelPermalink method on each resource.
Headless section
Create an unpublished section whose content and resources you can include in other pages. Consider this content structure:
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 pageSet the build options in front matter of the branch bundle, using the cascade keyword to apply the values to the descendant pages:
---
cascade:
- build:
list: local
publishResources: false
render: never
title: Headless section
---+++
title = 'Headless section'
[[cascade]]
[cascade.build]
list = 'local'
publishResources = false
render = 'never'
+++{
"cascade": [
{
"build": {
"list": "local",
"publishResources": false,
"render": "never"
}
}
],
"title": "Headless section"
}
Setting list to local includes the descendant pages in local page collections, such as the collection returned by the Pages method on the section page.
Use the Site.GetPage method in the home template to include the content and images on the home page:
{{ with site.GetPage "/headless" }}
{{ range .Pages }}
{{ .Content }}
{{ range .Resources.ByType "image" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
{{ end }}When you build the project, the public directory has this structure:
public/
├── headless/
│ ├── note-1/
│ │ ├── a.jpg
│ │ └── b.jpg
│ └── note-2/
│ ├── c.jpg
│ └── d.jpg
└── index.htmlHugo does not publish an HTML file for the section page or its descendant pages. Hugo publishes the page resources even though publishResources is false, because the template calls the RelPermalink method on each resource.
List without publishing
Publish a section page without publishing the descendant pages. For example, consider this content structure for a glossary:
content/
├── glossary/
│ ├── _index.md
│ ├── bar.md
│ ├── baz.md
│ └── foo.md
└── _index.mdSet the build options in front matter of the branch bundle, using the cascade keyword to apply the values to the descendant pages:
---
build:
render: always
cascade:
- build:
list: local
publishResources: false
render: never
title: Glossary
---+++
title = 'Glossary'
[build]
render = 'always'
[[cascade]]
[cascade.build]
list = 'local'
publishResources = false
render = 'never'
+++{
"build": {
"render": "always"
},
"cascade": [
{
"build": {
"list": "local",
"publishResources": false,
"render": "never"
}
}
],
"title": "Glossary"
}
Use the Pages method in the section template to render the glossary:
<dl>
{{ range .Pages }}
<dt>{{ .Title }}</dt>
<dd>{{ .Content }}</dd>
{{ end }}
</dl>When you build the project, the public directory has this structure:
public/
├── glossary/
│ └── index.html
└── index.htmlPublish without listing
Publish the descendant pages of a section without publishing the section page itself. Consider this content structure:
content/
├── books/
│ ├── _index.md
│ ├── book-1.md
│ └── book-2.md
└── _index.mdSet the build options in front matter of the branch bundle:
---
build:
list: never
render: never
title: Books
---+++
title = 'Books'
[build]
list = 'never'
render = 'never'
+++{
"build": {
"list": "never",
"render": "never"
},
"title": "Books"
}
When you build the project, the public directory has this structure:
public/
├── books/
│ ├── book-1/
│ │ └── index.html
│ └── book-2/
│ └── index.html
└── index.htmlConditionally hide a section
For 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 Hugo hides when you build for production. Consider this content structure:
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.mdSet the build options in front matter of the branch bundle, using the cascade keyword to apply the values to the descendant pages, and the target keyword to apply them only in the production environment:
cascade:
- build:
list: never
render: never
target:
environment: production
title: Internal
title = 'Internal'
[[cascade]]
[cascade.build]
list = 'never'
render = 'never'
[cascade.target]
environment = 'production'
{
"cascade": [
{
"build": {
"list": "never",
"render": "never"
},
"target": {
"environment": "production"
}
}
],
"title": "Internal"
}
When you build the project for production, the public directory has this structure:
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