hugo/docs/content/en/content-management/build-options.md
Bjørn Erik Pedersen 634938908e pagemeta: Make BuildConfig.Render an enum
Allowing links on pages without rendering them.

Fixes #7783
2020-10-06 14:06:10 +02:00

3.4 KiB

title linktitle description date publishdate keywords categories menu weight draft aliases toc
Build Options Build Options Build options help define how Hugo must treat a given page when building the site. 2020-03-02 2020-03-02
build
content
front matter
page resources
content management
docs
parent weight
content-management 31
31 false
/content/build-options/
true

They are stored in a reserved Front Matter object named _build with the following defaults:

_build:
  render: always
  list: always
  publishResources: true

render

If always, the page will be treated as a published page, holding its dedicated output files (index.html, etc...) and permalink.

{{< new-in "0.76.0" >}} We extended this property from a boolean to an enum in Hugo 0.76.0. 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

Note that we extended this property from a boolean to an enum in Hugo 0.68.0.

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, $page.Pages.
local
The page will be included in any local page collection, e.g. $page.RegularPages, $page.Pages. One use case for this would be to create fully navigable, but headless content sections. {{< new-in "0.68.0" >}}

If true, the page will be treated as part of the project's collections and, when appropriate, returned by Hugo's listing methods (.Pages, .RegularPages etc...).

publishResources

If set to true the [Bundle's Resources]({{< relref "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.

{{% note %}} Any page, regardless of their build options, will always be available using the [.GetPage]({{< relref "functions/GetPage" >}}) methods. {{% /note %}}


Illustrative use cases

Not publishing a page

Project needs a "Who We Are" content file for Front Matter and body to be used by the homepage but nowhere else.

# content/who-we-are.md`
title: Who we are
_build:
 list: false
 render: false
{{/* layouts/index.html */}}
<section id="who-we-are">
{{ with site.GetPage "who-we-are" }}
  {{ .Content }}
{{ end }}
</section>

Listing pages without publishing them

Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them.

To avoid setting the build options on every testimonials, one can use [cascade]({{< relref "/content-management/front-matter#front-matter-cascade" >}}) on the testimonial section's content file.

#content/testimonials/_index.md
title: Testimonials
# section build options:
_build:
  render: true
# children build options with cascade
cascade:
  _build:
    render: false
    list: true # default
{{/* layouts/_defaults/testimonials.html */}}
<section id="testimonials">
{{ range first 5 .Pages }}
  <blockquote cite="{{ .Params.cite }}">
    {{ .Content }}
  </blockquote>
{{ end }}
</section>