diff options
Diffstat (limited to 'docs/content/en/content-management/build-options.md')
-rw-r--r-- | docs/content/en/content-management/build-options.md | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md new file mode 100644 index 000000000..f402b9014 --- /dev/null +++ b/docs/content/en/content-management/build-options.md @@ -0,0 +1,94 @@ +--- +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: true + 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 +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>
\ No newline at end of file |