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