Build options

建置選項儲存在一個名為 build 的保留前置內容物件中，並具有以下預設值：

content/example/index.md

---
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 等。使用此選項可建立完全可導航但無頁面主檔的內容區段。
never

不將該頁面包含在任何頁面集合中。

publishResources

適用於頁面包裝，決定是否發佈相關聯的頁面資源。請指定以下之一：

true

永遠發佈資源。這是預設值。
false

僅在模板中調用其 Permalink、RelPermalink 或 Publish 方法時才發佈資源。

render

何時渲染頁面。請指定以下之一：

always

始終將頁面渲染到磁碟。這是預設值。
link

不將頁面渲染到磁碟，但分配 Permalink 和 RelPermalink 值。
never

永不將頁面渲染到磁碟，並將其從所有頁面集合中排除。

範例 – 無頁面主檔的頁面

建立一個未發佈的頁面，其內容和資源可以包含在其他頁面中。

content/
├── headless/
│   ├── a.jpg
│   ├── b.jpg
│   └── index.md  <-- 單一包裝
└── _index.md     <-- 首頁

在前置內容中設定建置選項：

content/headless/index.md

---
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/_default/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 文件。
儘管在前置內容中將 publishResources 設為 false，Hugo 仍發佈了頁面資源，因為我們在每個資源上調用了 RelPermalink 方法。這是預期行為。

範例 – 無頁面主檔的區段

建立一個未發佈的區段，其內容和資源可以包含在其他頁面中。

content/
├── headless/
│   ├── note-1/
│   │   ├── a.jpg
│   │   ├── b.jpg
│   │   └── index.md  <-- 單一包裝
│   ├── note-2/
│   │   ├── c.jpg
│   │   ├── d.jpg
│   │   └── index.md  <-- 單一包裝
│   └── _index.md     <-- 分支包裝
└── _index.md         <-- 首頁

在前置內容中設定建置選項，並使用 cascade 關鍵字將值「層疊」至子頁面。

content/headless/_index.md

---
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"
}

在上述前置內容中，注意我們將 list 設為 local，以便將子頁面包含在本地頁面集合中。

在首頁中包含該內容與圖片：

layouts/_default/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 文件。
儘管在前置內容中將 publishResources 設為 false，Hugo 正確地發佈了頁面資源，因為我們在每個資源上調用了 RelPermalink 方法。這是預期行為。

範例 – 僅列出，不發佈

發佈區段頁面，但不發佈子頁面。例如，建立一個術語表：

content/
├── glossary/
│   ├── _index.md
│   ├── bar.md
│   ├── baz.md
│   └── foo.md
└── _index.md

在前置內容中設定建置選項，並使用 cascade 關鍵字將值「層疊」至子頁面。

content/glossary/_index.md

---
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/list.html

<dl>
  {{ range .Pages }}
    <dt>{{ .Title }}</dt>
    <dd>{{ .Content }}</dd>
  {{ end }}
</dl>

發佈後的網站結構如下：

public/
├── glossary/
│   └── index.html
└── index.html

範例 – 發佈但不列出

發佈區段的子頁面，但不發佈該區段頁面本身。

content/
├── books/
│   ├── _index.md
│   ├── book-1.md
│   └── book-2.md
└── _index.md

在前置內容中設定建置選項：

content/books/_index.md

---
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

範例 – 有條件隱藏區段

考慮此範例。一個文件網站有一個由貢獻者組成的團隊，這些貢獻者可存取 20 個自訂短代碼。每個短代碼都有多個參數，並需要文件供貢獻者參考使用。

與其建立短代碼的外部文件，可以包含一個「內部」區段，在建置正式網站時隱藏該區段。

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

在前置內容中設定建置選項，使用 cascade 關鍵字將值「層疊」至子頁面，並使用 target 關鍵字將設定目標設為生產環境。

content/internal/_index.md.

cascade:
- _target:
    environment: production
  build:
    list: never
    render: never
title: Internal

title = 'Internal'
[[cascade]]
  [cascade._target]
    environment = 'production'
  [cascade.build]
    list = 'never'
    render = 'never'

{
   "cascade": [
      {
         "_target": {
            "environment": "production"
         },
         "build": {
            "list": "never",
            "render": "never"
         }
      }
   ],
   "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

在上述範例中，請注意：

internal 區段及其子頁面並未在生產網站中發佈，因為在前置內容中設定了 render = 'never' 和 list = 'never'，並且目標環境為 production。
如果切換到非生產環境，例如本地開發環境，internal 區段及其內容仍然可以被渲染並供測試。

範例 – 不同環境的建置選項

在多環境開發中，您可以根據不同的環境需求調整建置選項。例如，在開發環境中渲染未完成的功能，而在生產環境中則隱藏這些內容。

假設我們有以下網站結構：

content/
├── experiments/
│   ├── feature-1.md
│   ├── feature-2.md
│   └── _index.md
└── _index.md

在前置內容中設定建置選項，以根據環境進行調整：

content/experiments/_index.md

title = 'Experiments'
[build]
render = 'never'
list = 'never'
[[cascade]]
[cascade._target]]
environment = 'development'
[cascade.build]
  render = 'always'
  list = 'local'

行為解析

在生產環境中，experiments 區段及其內容都不會渲染。
在開發環境中，experiments 區段及其內容會被渲染並包含在本地頁面集合中。

發佈後的生產網站結構如下：

public/
└── index.html

而在開發環境中，網站結構如下：

public/
├── experiments/
│   ├── feature-1/
│   │   └── index.html
│   ├── feature-2/
│   │   └── index.html
│   └── index.html
└── index.html

總結

Hugo 的建置選項提供了強大的靈活性，允許您控制內容的渲染、資源發佈以及內容是否出現在頁面集合中。這些選項可根據您的網站需求，靈活地配置頁面及資源的建置行為。

透過使用 build 物件中的 list、publishResources 和 render 參數，您可以實現以下目標：

創建僅供內部使用的頁面或區段。
在生產環境中隱藏特定內容。
控制資源的發佈行為，減少不必要的資源發佈。
在多環境中調整建置選項，以便在開發與生產環境中達到不同的效果。

這使得 Hugo 不僅是靜態網站生成器，也成為了一個可針對內容精確控制的靈活工具。