build-options.md (3398B)
1 ---
2 title: Build Options
3 linktitle: Build Options
4 description: Build options help define how Hugo must treat a given page when building the site.
5 date: 2020-03-02
6 publishdate: 2020-03-02
7 keywords: [build,content,front matter, page resources]
8 categories: ["content management"]
9 menu:
10 docs:
11 parent: "content-management"
12 weight: 31
13 weight: 31 #rem
14 draft: false
15 aliases: [/content/build-options/]
16 toc: true
17 ---
18
19 They are stored in a reserved Front Matter object named `_build` with the following defaults:
20
21 {{< code-toggle >}}
22 _build:
23 render: always
24 list: always
25 publishResources: true
26 {{< /code-toggle >}}
27
28 #### render
29 If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink.
30
31 {{< new-in "0.76.0" >}} We extended this property from a boolean to an enum in Hugo 0.76.0. Valid values are:
32
33 never
34 : The page will not be included in any page collection.
35
36 always (default)
37 : The page will be rendered to disk and get a `RelPermalink` etc.
38
39 link
40 : The page will be not be rendered to disk, but will get a `RelPermalink`.
41
42 #### list
43
44 Note that we extended this property from a boolean to an enum in Hugo 0.68.0.
45
46 Valid values are:
47
48 never
49 : The page will not be included in any page collection.
50
51 always (default)
52 : The page will be included in all page collections, e.g. `site.RegularPages`, `$page.Pages`.
53
54 local
55 : 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" >}}
56
57 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...).
58
59 #### publishResources
60
61 If set to true the [Bundle's Resources]({{< relref "content-management/page-bundles" >}}) will be published.
62 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.
63
64 {{% note %}}
65 Any page, regardless of their build options, will always be available using the [`.GetPage`]({{< relref "functions/GetPage" >}}) methods.
66 {{% /note %}}
67
68 ------
69
70 ### Illustrative use cases
71
72 #### Not publishing a page
73 Project needs a "Who We Are" content file for Front Matter and body to be used by the homepage but nowhere else.
74
75 ```yaml
76 # content/who-we-are.md`
77 title: Who we are
78 _build:
79 list: false
80 render: false
81 ```
82
83 ```go-html-template
84 {{/* layouts/index.html */}}
85 <section id="who-we-are">
86 {{ with site.GetPage "who-we-are" }}
87 {{ .Content }}
88 {{ end }}
89 </section>
90 ```
91
92 #### Listing pages without publishing them
93
94 Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them.
95
96 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.
97
98 {{< code-toggle >}}
99 title: Testimonials
100 _build:
101 render: true
102 cascade:
103 _build:
104 render: false
105 list: true # default
106 {{< /code-toggle >}}
107
108 ```go-html-template
109 {{/* layouts/_defaults/testimonials.html */}}
110 <section id="testimonials">
111 {{ range first 5 .Pages }}
112 <blockquote cite="{{ .Params.cite }}">
113 {{ .Content }}
114 </blockquote>
115 {{ end }}
116 </section>