Hugo 构建选项
构建选项帮助定义 Hugo 在构建站点时如何处理给定页面。
构建选项存储在名为 build 的保留 front matter 对象中，默认值如下：
---
build:
list: always
publishResources: true
render: always
---+++
[build]
list = 'always'
publishResources = true
render = 'always'
+++{
"build": {
"list": "always",
"publishResources": true,
"render": "always"
}
}
- list
- 何时将页面包含在页面集合中。指定以下值之一：
always：将页面包含在 所有 页面集合中。例如，site.RegularPages、.Pages等。这是默认值。local：将页面包含在 本地 页面集合中。例如，.RegularPages、.Pages等。使用此选项创建完全可导航但无头的内容 section。never：不将页面包含在 任何 页面集合中。
- publishResources
- 适用于 page bundles，决定是否发布关联的 page resources。指定以下值之一：
true：始终发布资源。这是默认值。false：仅在模板中调用其Permalink、RelPermalink或Publish方法时发布资源。
- render
- 何时渲染页面。指定以下值之一：
always：始终将页面渲染到磁盘。这是默认值。link：不将页面渲染到磁盘，但分配Permalink和RelPermalink值。never：从不将页面渲染到磁盘，并将其从所有页面集合中排除。
无论页面的构建选项如何，始终可以通过使用 .Page.GetPage 或 .Site.GetPage 方法来访问页面。
示例 – 无头页面
创建一个未发布的页面，其内容和资源可以包含在其他页面中。
content/
├── headless/
│ ├── a.jpg
│ ├── b.jpg
│ └── index.md <-- 叶 bundle
└── _index.md <-- 首页在 front matter 中设置构建选项：
---
build:
list: never
publishResources: false
render: never
title: Headless page
---+++
title = 'Headless page'
[build]
list = 'never'
publishResources = false
render = 'never'
+++{
"build": {
"list": "never",
"publishResources": false,
"render": "never"
},
"title": "Headless page"
}
要在首页上包含内容和图片：
layouts/home.html
{{ with .Site.GetPage "/headless" }}
{{ .Content }}
{{ range .Resources.ByType "image" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}发布的站点将具有以下结构：
public/
├── headless/
│ ├── a.jpg
│ └── b.jpg
└── index.html在上面的示例中，请注意：
- Hugo 没有为页面发布 HTML 文件。
- 尽管在 front matter 中将
publishResources设置为false，但 Hugo 发布了 page resources，因为我们对每个资源调用了RelPermalink方法。这是预期行为。
示例 – 无头 section
创建一个未发布的 section，其内容和资源可以包含在其他页面中。
content/
├── headless/
│ ├── note-1/
│ │ ├── a.jpg
│ │ ├── b.jpg
│ │ └── index.md <-- 叶 bundle
│ ├── note-2/
│ │ ├── c.jpg
│ │ ├── d.jpg
│ │ └── index.md <-- 叶 bundle
│ └── _index.md <-- 分支 bundle
└── _index.md <-- 首页在 front matter 中设置构建选项，使用 cascade 关键字将值"级联"到后代页面。
---
cascade:
- build:
list: local
publishResources: false
render: never
title: Headless section
---+++
title = 'Headless section'
[[cascade]]
[cascade.build]
list = 'local'
publishResources = false
render = 'never'
+++{
"cascade": [
{
"build": {
"list": "local",
"publishResources": false,
"render": "never"
}
}
],
"title": "Headless section"
}
在上面的 front matter 中，请注意我们将 list 设置为 local，以便在本地页面集合中包含后代页面。
要在首页上包含内容和图片：
layouts/home.html
{{ with .Site.GetPage "/headless" }}
{{ range .Pages }}
{{ .Content }}
{{ range .Resources.ByType "image" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
{{ end }}发布的站点将具有以下结构：
public/
├── headless/
│ ├── note-1/
│ │ ├── a.jpg
│ │ └── b.jpg
│ └── note-2/
│ ├── c.jpg
│ └── d.jpg
└── index.html在上面的示例中，请注意：
- Hugo 没有为页面发布 HTML 文件。
- 尽管在 front matter 中将
publishResources设置为false，但 Hugo 正确地发布了 page resources，因为我们对每个资源调用了RelPermalink方法。这是预期行为。
示例 – 列出而不发布
发布 section 页面而不发布后代页面。例如，创建术语表：
content/
├── glossary/
│ ├── _index.md
│ ├── bar.md
│ ├── baz.md
│ └── foo.md
└── _index.md在 front matter 中设置构建选项，使用 cascade 关键字将值"级联"到后代页面。
---
build:
render: always
cascade:
- build:
list: local
publishResources: false
render: never
title: Glossary
---+++
title = 'Glossary'
[build]
render = 'always'
[[cascade]]
[cascade.build]
list = 'local'
publishResources = false
render = 'never'
+++{
"build": {
"render": "always"
},
"cascade": [
{
"build": {
"list": "local",
"publishResources": false,
"render": "never"
}
}
],
"title": "Glossary"
}
要渲染术语表：
layouts/glossary/section.html
<dl>
{{ range .Pages }}
<dt>{{ .Title }}</dt>
<dd>{{ .Content }}</dd>
{{ end }}
</dl>发布的站点将具有以下结构：
public/
├── glossary/
│ └── index.html
└── index.html示例 – 发布而不列出
发布 section 的后代页面而不发布 section 页面本身。
content/
├── books/
│ ├── _index.md
│ ├── book-1.md
│ └── book-2.md
└── _index.md在 front matter 中设置构建选项：
---
build:
list: never
render: never
title: Books
---+++
title = 'Books'
[build]
list = 'never'
render = 'never'
+++{
"build": {
"list": "never",
"render": "never"
},
"title": "Books"
}
发布的站点将具有以下结构：
public/
├── books/
│ ├── book-1/
│ │ └── index.html
│ └── book-2/
│ └── index.html
└── index.html示例 – 有条件地隐藏 section
考虑以下示例。一个文档站点有一个贡献者团队，可以访问 20 个自定义 shortcode。每个 shortcode 接受几个参数，需要文档供贡献者在使用时参考。
与其使用外部文档来记录 shortcode，不如包含一个"内部"section，在构建生产站点时隐藏它。
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在 front matter 中设置构建选项，使用 cascade 关键字将值"级联"到后代页面，并使用 target 关键字针对生产环境。
cascade:
- build:
list: never
render: never
target:
environment: production
title: Internal
title = 'Internal'
[[cascade]]
[cascade.build]
list = 'never'
render = 'never'
[cascade.target]
environment = 'production'
{
"cascade": [
{
"build": {
"list": "never",
"render": "never"
},
"target": {
"environment": "production"
}
}
],
"title": "Internal"
}
生产站点将具有以下结构：
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