mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-14 12:04:57 -04:00
Clean up build option descriptions and examples
This commit is contained in:
Joe Mooring
Joe Mooring
parent
f46d313088
commit
dff3c4abb8
@ -12,112 +12,310 @@ toc: true
|
||||
aliases: [/content/build-options/]
|
||||
---
|
||||
|
||||
They are stored in a reserved front matter object named `_build` with the following defaults:
|
||||
Build options are stored in a reserved front matter object named `_build` with these defaults:
|
||||
|
||||
{{< code-toggle >}}
|
||||
_build:
|
||||
render: always
|
||||
list: always
|
||||
publishResources: true
|
||||
{{< code-toggle file="content/example/index.md" fm=true >}}
|
||||
[_build]
|
||||
list = 'always'
|
||||
publishResources = true
|
||||
render = 'always'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### render
|
||||
|
||||
If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink.
|
||||
list
|
||||
: When to include the page within page collections. Specify one of:
|
||||
|
||||
Valid values are:
|
||||
- `always`
|
||||
: Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value.
|
||||
|
||||
- `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
|
||||
|
||||
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`, `.Pages`.
|
||||
- `local`
|
||||
: The page will be included in any _local_ page collection, e.g. `.RegularPages`, `.Pages`. One use case for this would be to create fully navigable, but headless content sections.
|
||||
: Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections.
|
||||
|
||||
#### publishResources
|
||||
- `never`
|
||||
: Do not include the page in _any_ page collection.
|
||||
|
||||
If set to `true` (default) the [Bundle's Resources](/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.
|
||||
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 invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template.
|
||||
|
||||
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 include it in all page collections.
|
||||
|
||||
- `never`
|
||||
: Never render the page to disk, and exclude it from all page collections.
|
||||
|
||||
[page bundles]: content-management/page-bundles
|
||||
[page resources]: /content-management/page-resources
|
||||
[`Permalink`]: /methods/resource/permalink
|
||||
[`RelPermalink`]: /methods/resource/relpermalink
|
||||
[`Publish`]: /methods/resource/publish
|
||||
|
||||
{{% note %}}
|
||||
Any page, regardless of their build options, will always be available using the [`.GetPage`](/methods/page/getpage) methods.
|
||||
Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method.
|
||||
|
||||
[`.Page.GetPage`]: /methods/page/getpage
|
||||
[`.Site.GetPage`]: /methods/site/getpage
|
||||
{{% /note %}}
|
||||
|
||||
### Illustrative use cases
|
||||
## Example -- headless page
|
||||
|
||||
#### Not publishing a page
|
||||
Create a unpublished page whose content and resources can be included in other pages.
|
||||
|
||||
Project needs a "Who We Are" content file for front matter and body to be used by the homepage but nowhere else.
|
||||
```text
|
||||
content/
|
||||
├── headless/
|
||||
│ ├── a.jpg
|
||||
│ ├── b.jpg
|
||||
│ └── index.md <-- leaf bundle
|
||||
└── _index.md <-- home page
|
||||
```
|
||||
|
||||
{{< code-toggle file="content/who-we-are.md" fm=true >}}
|
||||
title: Who we are
|
||||
_build:
|
||||
list: false
|
||||
render: false
|
||||
Set the build options in front matter:
|
||||
|
||||
{{< code-toggle file=content/headless/index.md fm=true >}}
|
||||
title = 'Headless page'
|
||||
[_build]
|
||||
list = 'never'
|
||||
publishResources = false
|
||||
render = 'never'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{< code file="layouts/index.html" >}}
|
||||
<section id="who-we-are">
|
||||
{{ with site.GetPage "who-we-are" }}
|
||||
To include the content and images on the home page:
|
||||
|
||||
{{< code file="layouts/_default/home.html" lang=go-html-template >}}
|
||||
{{ with .Site.GetPage "/headless" }}
|
||||
{{ .Content }}
|
||||
{{ range .Resources.ByType "image" }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
</section>
|
||||
{{< /code >}}
|
||||
|
||||
#### Listing pages without publishing them
|
||||
The published site will have this structure:
|
||||
|
||||
Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them.
|
||||
```text
|
||||
public/
|
||||
├── headless/
|
||||
│ ├── a.jpg
|
||||
│ └── b.jpg
|
||||
└── index.html
|
||||
```
|
||||
|
||||
To avoid setting the build options on every testimonials, one can use [`cascade`](/content-management/front-matter#front-matter-cascade) on the testimonial section's content file.
|
||||
In the example above, note that:
|
||||
|
||||
{{< code-toggle >}}
|
||||
title: Testimonials
|
||||
_build:
|
||||
render: true
|
||||
cascade:
|
||||
_build:
|
||||
render: false
|
||||
list: true # default
|
||||
1. Hugo did not publish an HTML file for the page.
|
||||
2. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
|
||||
|
||||
## Example -- headless section
|
||||
|
||||
Create a unpublished section whose content and resources can be included in other pages.
|
||||
|
||||
[branch bundle]: /content-management/page-bundles
|
||||
|
||||
```text
|
||||
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 page
|
||||
```
|
||||
|
||||
Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
|
||||
|
||||
{{< code-toggle file=content/headless/_index.md fm=true >}}
|
||||
title = 'Headless section'
|
||||
[[cascade]]
|
||||
[cascade._build]
|
||||
list = 'local'
|
||||
publishResources = false
|
||||
render = 'never'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{< code file="layouts/_defaults/testimonials.html" >}}
|
||||
<section id="testimonials">
|
||||
{{ range first 5 .Pages }}
|
||||
<blockquote cite="{{ .Params.cite }}">
|
||||
In the front matter above, note that we have set `list` to `local` to include the descendant pages in local page collections.
|
||||
|
||||
To include the content and images on the home page:
|
||||
|
||||
{{< code file="layouts/_default/home.html" lang=go-html-template >}}
|
||||
{{ with .Site.GetPage "/headless" }}
|
||||
{{ range .Pages }}
|
||||
{{ .Content }}
|
||||
</blockquote>
|
||||
{{ range .Resources.ByType "image" }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
</section>
|
||||
{{< /code >}}
|
||||
|
||||
#### Not rendering an index file for a hidden section
|
||||
The published site will have this structure:
|
||||
|
||||
Website wants to hide a section from sitemap, menu and other navigation, but still wants to have all children rendered.
|
||||
```text
|
||||
public/
|
||||
├── headless/
|
||||
│ ├── note-1/
|
||||
│ │ ├── a.jpg
|
||||
│ │ └── b.jpg
|
||||
│ └── note-2/
|
||||
│ ├── c.jpg
|
||||
│ └── d.jpg
|
||||
└── index.html
|
||||
```
|
||||
|
||||
See the forum question: [Disable generating empty index.html pages created for sections](https://discourse.gohugo.io/t/disable-generating-empty-index-html-pages-created-for-sections/11036/1)
|
||||
In the example above, note that:
|
||||
|
||||
This use case leverages [`cascade`](/content-management/front-matter#front-matter-cascade) as well.
|
||||
1. Hugo did not publish an HTML file for the page.
|
||||
2. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
|
||||
|
||||
{{< code-toggle >}}
|
||||
title: Section without index file
|
||||
url: /hidden-section/
|
||||
_build:
|
||||
render: never
|
||||
list: never
|
||||
publishResources: false
|
||||
cascade:
|
||||
_build:
|
||||
list: false
|
||||
render: true
|
||||
## Example -- list without publishing
|
||||
|
||||
Publish a section page without publishing the descendant pages. For example, to create a glossary:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── glossary/
|
||||
│ ├── _index.md
|
||||
│ ├── bar.md
|
||||
│ ├── baz.md
|
||||
│ └── foo.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
|
||||
|
||||
{{< code-toggle file="content/glossary/_index.md" fm=true >}}
|
||||
title = 'Glossary'
|
||||
[_build]
|
||||
render = 'always'
|
||||
[[cascade]]
|
||||
[cascade._build]
|
||||
list = 'local'
|
||||
publishResources = false
|
||||
render = 'never'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To render the glossary:
|
||||
|
||||
{{< code file=layouts/glossary/list.html lang=go-html-template >}}
|
||||
<dl>
|
||||
{{ range .Pages }}
|
||||
<dt>{{ .Title }}</dt>
|
||||
<dd>{{ .Content }}</dd>
|
||||
{{ end }}
|
||||
</dl>
|
||||
{{< /code >}}
|
||||
|
||||
The published site will have this structure:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── glossary/
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
## Example -- publish without listing
|
||||
|
||||
Publish a section's descendant pages without publishing the section page itself.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── books/
|
||||
│ ├── _index.md
|
||||
│ ├── book-1.md
|
||||
│ └── book-2.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Set the build options in front matter:
|
||||
|
||||
{{< code-toggle file=content/books/_index.md >}}
|
||||
title = 'Books'
|
||||
[_build]
|
||||
render = 'never'
|
||||
list = 'never'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The published site will have this structure:
|
||||
|
||||
```html
|
||||
public/
|
||||
├── books/
|
||||
│ ├── book-1/
|
||||
│ │ └── index.html
|
||||
│ └── book-2/
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
## Example -- conditionally hide section
|
||||
|
||||
Consider this 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 is hidden when building the production site.
|
||||
|
||||
```text
|
||||
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.md
|
||||
```
|
||||
|
||||
Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages, and use the `target` keyword to target the production environment.
|
||||
|
||||
{{< code-toggle file=content/internal/_index.md >}}
|
||||
title = 'Internal'
|
||||
[[cascade]]
|
||||
[cascade._build]
|
||||
render = 'never'
|
||||
list = 'never'
|
||||
[cascade._target]
|
||||
environment = 'production'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The production site will have this structure:
|
||||
|
||||
```html
|
||||
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
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user