mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
efa74c5c6e
ac2c4a487 Update documentation for Ugly URLs (#1082) 88bdec17a Change 072.0 to 0.72.0 in release post's description 2aa7d7818 Update rss.md (#1104) c80677aeb Update quick-start.md (#1076) d04196bbd Minor spelling and capitalization fixes 837d2feba Fixed spelling mistake 67dc78e12 Update installing.md ce280c5d6 Update relurl.md bb4d0e703 Capitalization and Redirecting URL fixes e1fecada0 Update partials.md 1d99bb182 Typos and whitespacing issues fixed b20dba125 actually fix index function link this time f47d6f1e3 Fixing typos, whitespace issues and links dc82309b9 fix link to the index function 1eab0cbea add missing word (#1130) 9c3ee62ae more fixes e9bc5880a whitespace, typos and HTTPS fixes 93b806493 Add missing word to Module section 80ced9062 Display image on page bundles page. 727029b0a Update index.md 51fc48e4d Release 0.72.0 1ff68ac3b releaser: Add release notes to /docs for release of 0.72.0 f74a25b92 common/maps: Add Scratch.Values 2fd83db96 Add redirect support to the server bdfccf9f4 Fix typo in install instructions e12737ea6 Create SUPPORT.md git-subtree-dir: docs git-subtree-split: ac2c4a4871e90ddfb180f23704ce7ec9023529ca
108 lines
3 KiB
Markdown
108 lines
3 KiB
Markdown
---
|
|
title: Build Options
|
|
linktitle: Build Options
|
|
description: Build options help define how Hugo must treat a given page when building the site.
|
|
date: 2020-03-02
|
|
publishdate: 2020-03-02
|
|
keywords: [build,content,front matter, page resources]
|
|
categories: ["content management"]
|
|
menu:
|
|
docs:
|
|
parent: "content-management"
|
|
weight: 31
|
|
weight: 31 #rem
|
|
draft: false
|
|
aliases: [/content/build-options/]
|
|
toc: true
|
|
---
|
|
|
|
They are stored in a reserved Front Matter object named `_build` with the following defaults:
|
|
|
|
```yaml
|
|
_build:
|
|
render: true
|
|
list: always
|
|
publishResources: true
|
|
```
|
|
|
|
#### render
|
|
If true, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink.
|
|
|
|
#### 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.
|
|
|
|
```yaml
|
|
# content/who-we-are.md`
|
|
title: Who we are
|
|
_build:
|
|
list: false
|
|
render: false
|
|
```
|
|
|
|
```go-html-template
|
|
{{/* 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.
|
|
|
|
```yaml
|
|
#content/testimonials/_index.md
|
|
title: Testimonials
|
|
# section build options:
|
|
_build:
|
|
render: true
|
|
# children build options with cascade
|
|
cascade:
|
|
_build:
|
|
render: false
|
|
list: true # default
|
|
```
|
|
|
|
```go-html-template
|
|
{{/* layouts/_defaults/testimonials.html */}}
|
|
<section id="testimonials">
|
|
{{ range first 5 .Pages }}
|
|
<blockquote cite="{{ .Params.cite }}">
|
|
{{ .Content }}
|
|
</blockquote>
|
|
{{ end }}
|
|
</section>
|