Front matter

概覽

每個內容檔案頂部的 Front Matter 是元數據，具有以下功能：

描述內容
擴充內容
建立與其他內容的關聯
控制網站的發佈結構
決定模板選擇

提供 Front Matter 時，使用一種序列化格式，選擇 JSON、TOML 或 YAML 其中之一。Hugo 通過檢查分隔符來確定 Front Matter 格式，這些分隔符將 Front Matter 與頁面內容分開。

請透過在下方切換不同序列化格式來查看 Front Matter 分隔符範例。

content/example.md

---
date: 2024-02-02T04:14:54-08:00
draft: false
params:
  author: John Smith
title: 範例
weight: 10
---

+++
date = 2024-02-02T04:14:54-08:00
draft = false
title = '範例'
weight = 10
[params]
  author = 'John Smith'
+++

{
   "date": "2024-02-02T04:14:54-08:00",
   "draft": false,
   "params": {
      "author": "John Smith"
   },
   "title": "範例",
   "weight": 10
}

Front Matter 欄位可以是 [布林值]、[整數]、[浮點數]、[字串]、[陣列] 或 [映射]。請注意，TOML 格式也支援不加引號的日期/時間值。

欄位

最常見的 Front Matter 欄位有 date、draft、title 和 weight，但您可以使用以下任何欄位來指定元數據。

aliases

(字串陣列) 一個包含一個或多個別名的陣列，每個別名都是一個相對 URL，將把瀏覽器重定向到當前位置。可以透過 Aliases 方法在模板中訪問這些值，請參見 aliases 部分了解詳情。

build

(映射) 一個 [建構選項] 的映射。

cascade

(映射) 一個 Front Matter 鍵的映射，其值會傳遞給頁面後代，除非被自身或更接近的祖先的 cascade 覆蓋。請參見 cascade 部分了解詳情。

date

(字串) 與頁面相關聯的日期，通常是創建日期。請注意，TOML 格式也支援不加引號的日期/時間值。請參見 dates 部分了解範例。可以透過 Date 方法在模板中訪問此值。

description

(字串) 概念上與頁面 summary 不同，description 通常會在發佈的 HTML 檔案中的 head 元素內呈現為 meta 元素。可以透過 Description 方法在模板中訪問此值。

draft

(布林值) 如果設為 true，該頁面將不會被渲染，除非您在 hugo 命令中傳遞 --buildDrafts 標誌。可以透過 Draft 方法在模板中訪問此值。

expiryDate

(字串) 頁面的過期日期。過期日期當天或之後，該頁面將不會被渲染，除非您在 hugo 命令中傳遞 --buildExpired 標誌。請注意，TOML 格式也支援不加引號的日期/時間值。請參見 dates 部分了解範例。可以透過 ExpiryDate 方法在模板中訪問此值。

headless

(布林值) 適用於 leaf bundles，如果設為 true，此值會將 render 和 list [建構選項] 設為 never，創建一個無頭的頁面資源。

isCJKLanguage

(布林值) 如果內容語言屬於 CJK 家族，則設為 true。此值會影響 Hugo 如何計算字數，並影響 WordCount、FuzzyWordCount、ReadingTime 和 Summary 方法所返回的值。

keywords

(字串陣列) 關鍵字的陣列，通常會在發佈的 HTML 檔案中的 head 元素內呈現為 meta 元素，或用作 [分類法] 來分類內容。可以透過 Keywords 方法在模板中訪問這些值。

lastmod

(字串) 頁面最後修改的日期。請注意，TOML 格式也支援不加引號的日期/時間值。請參見 dates 部分了解範例。可以透過 Lastmod 方法在模板中訪問此值。

layout

(字串) 提供模板名稱來 [指定特定模板]，覆蓋默認的 [模板查找順序]。將值設為模板的基本檔案名稱（不包括副檔名）。可以透過 Layout 方法在模板中訪問此值。

linkTitle

(字串) 通常是 title 的較短版本。可以透過 LinkTitle 方法在模板中訪問此值。

markup

(字串) 對應於支持的內容格式的識別符。如果未提供，Hugo 會根據檔案副檔名來判斷內容渲染器。

menus

(字串、字串陣列 或 映射) 如果設置，Hugo 會將頁面加入到指定的菜單中。請參見 menus 頁面了解詳情。

modified

lastmod 的別名。

outputs

(字串陣列) 渲染的 [輸出格式]。

params

New in v0.123.0

（map）一個自定義的頁面參數集合。

pubdate

別名為 publishDate。

publishDate

（string）頁面的發佈日期。發佈日期之前，頁面不會被渲染，除非你使用 --buildFuture 標誌運行 hugo 命令。注意，TOML 格式也支持未加引號的日期/時間值。詳情請參見日期部分中的範例。你可以在模板中使用 PublishDate 方法來訪問此值。

published

別名為 publishDate。

resources

（map 陣列）一個包含頁面資源的陣列，用來提供頁面資源的元數據。

sitemap

（map）一組 Sitemap 設定選項。詳情請參見 sitemap 範本頁面。在模板中，你可以使用 Sitemap 方法來訪問此值。

slug

（string）覆蓋 URL 路徑的最後一部分。對於區段頁面無效。詳情請參見 URL 管理頁面。在模板中，你可以使用 Slug 方法來訪問此值。

summary

（string）概念上與頁面 description 不同，摘要通常用來總結內容或作為引導讀者訪問頁面的提示。在模板中，可以使用 Summary 方法來訪問此值。

title

（string）頁面標題。在模板中，可以使用 Title 方法來訪問此值。

translationKey

（string）一個任意值，用來將同一頁面的不同語言翻譯聯繫起來，對於翻譯頁面沒有共同路徑的情況特別有用。在模板中，你可以使用 TranslationKey 方法來訪問此值。

type

（string）頁面類型，覆蓋從頁面所在的區段推導出的值。在模板中，可以使用 Type 方法來訪問此值。

unpublishdate

別名為 expirydate。

url

（string）覆蓋整個 URL 路徑。適用於常規頁面和區段頁面。詳情請參見 URL 管理頁面。

weight

（int）頁面的權重，用來在頁面集合中對頁面進行排序。在模板中，你可以使用 Weight 方法來訪問此值。

參數

New in v0.123.0

在前置內容中通過 params 關鍵字指定自定義頁面參數：

content/example.md

---
date: 2024-02-02T04:14:54-08:00
draft: false
params:
  author: John Smith
title: Example
weight: 10
---

+++
date = 2024-02-02T04:14:54-08:00
draft = false
title = 'Example'
weight = 10
[params]
  author = 'John Smith'
+++

{
   "date": "2024-02-02T04:14:54-08:00",
   "draft": false,
   "params": {
      "author": "John Smith"
   },
   "title": "Example",
   "weight": 10
}

在模板中，可以使用 Params 或 Param 方法來訪問這些值。

Hugo 提供了嵌入模板，可選擇性地將元數據插入渲染頁面的 head 元素中。這些嵌入模板預期以下前置內容參數：

參數	資料類型	使用於這些嵌入模板
`audio`	`[]string`	`opengraph.html`
`images`	`[]string`	`opengraph.html`, `schema.html`, `twitter_cards.html`
`videos`	`[]string`	`opengraph.html`

若前置內容中未提供參數，嵌入模板將會跳過該參數，但若資料類型不正確則會拋出錯誤。

分類法

通過在前置內容中添加分類詞來對內容進行分類。例如，使用以下站點配置：

hugo.

taxonomies:
  genre: genres
  tag: tags

[taxonomies]
  genre = 'genres'
  tag = 'tags'

{
   "taxonomies": {
      "genre": "genres",
      "tag": "tags"
   }
}

按照以下方式添加分類詞：

content/example.md

---
date: 2024-02-02T04:14:54-08:00
draft: false
genres:
- mystery
- romance
params:
  author: John Smith
tags:
- red
- blue
title: Example
weight: 10
---

+++
date = 2024-02-02T04:14:54-08:00
draft = false
genres = ['mystery', 'romance']
tags = ['red', 'blue']
title = 'Example'
weight = 10
[params]
  author = 'John Smith'
+++

{
   "date": "2024-02-02T04:14:54-08:00",
   "draft": false,
   "genres": [
      "mystery",
      "romance"
   ],
   "params": {
      "author": "John Smith"
   },
   "tags": [
      "red",
      "blue"
   ],
   "title": "Example",
   "weight": 10
}

你可以將分類詞添加到這些頁面類型的前置內容中：

home
page
section
taxonomy
term

在模板中，可以使用 Params 或 GetTerms 方法來訪問分類詞。例如：

layouts/_default/single.html

{{ with .GetTerms "tags" }}
  <p>標籤</p>
  <ul>
    {{ range . }}
      <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
    {{ end }}
  </ul>
{{ end }}

繼承

任何節點都可以將一組前置內容值傳遞給其後代頁面。

目標特定頁面

cascade 區塊可以是帶有選項性 _target 關鍵字的陣列，讓你在傳遞值時針對不同的頁面集合。

content/_index.md

---
cascade:
- _target:
    kind: page
    lang: en
    path: /articles/**
  params:
    background: yosemite.jpg
- _target:
    kind: section
  params:
    background: goldenbridge.jpg
title: 首頁
---

+++
title = '首頁'
[[cascade]]
  [cascade._target]
    kind = 'page'
    lang = 'en'
    path = '/articles/**'
  [cascade.params]
    background = 'yosemite.jpg'
[[cascade]]
  [cascade._target]
    kind = 'section'
  [cascade.params]
    background = 'goldenbridge.jpg'
+++

{
   "cascade": [
      {
         "_target": {
            "kind": "page",
            "lang": "en",
            "path": "/articles/**"
         },
         "params": {
            "background": "yosemite.jpg"
         }
      },
      {
         "_target": {
            "kind": "section"
         },
         "params": {
            "background": "goldenbridge.jpg"
         }
      }
   ],
   "title": "首頁"
}

你可以使用這些關鍵字的任意組合來指定一組頁面：

path

（string）匹配 /content 下內容路徑的 Glob 模式。使用 Unix 格式的斜杠。請注意，這是虛擬路徑，因此以掛載根目錄為起點。匹配支持雙星號，你可以使用 /blog/*/** 來匹配從第三層開始及以後的任何頁面。

kind

（string）匹配頁面類型的 Glob 模式，例如 {home,section}。

lang

（string）匹配頁面語言的 Glob 模式，例如 {en,sv}。

environment

（string）匹配構建環境的 Glob 模式，例如 “{production,development}”

上述任一項都可以省略。

範例

content/posts/_index.md

---
cascade:
  params:
    banner: images/typewriter.jpg
date: 2024-02-01T21:25:36-08:00
title: 文章
---

+++
date = 2024-02-01T21:25:36-08:00
title = '文章'
[cascade]
  [cascade.params]
    banner = 'images/typewriter.jpg'
+++

{
   "cascade": {
      "params": {
         "banner": "images/typewriter.jpg"
      }
   },
   "date": "2024-02-01T21:25:36-08:00",
   "title": "文章"
}

在上述範例中，當調用 .Params.banner 時，文章區段頁面及其後代頁面將返回 images/typewriter.jpg，除非：

該後代頁面有自己的 banner 值
或更接近的祖先節點有自己的 cascade.banner 值。

Emacs Org Mode

如果你的內容格式是 Emacs Org Mode，你可以使用 Org Mode 關鍵字提供前置內容。例如：

content/example.org

#+TITLE: 範例
#+DATE: 2024-02-02T04:14:54-08:00
#+DRAFT: false
#+AUTHOR: John Smith
#+GENRES: mystery
#+GENRES: romance
#+TAGS: red
#+TAGS: blue
#+WEIGHT: 10

注意，你也可以在同一行中指定陣列元素：

content/example.org

#+TAGS[]: red blue

日期

當填寫日期欄位時，無論是自定義頁面參數還是四個預定義的欄位（date、expiryDate、lastmod、publishDate），請使用以下可解析的格式：

格式	時區
`2023-10-15T13:18:50-07:00`	`America/Los_Angeles`
`2023-10-15T13:18:50-0700`	`America/Los_Angeles`
`2023-10-15T13:18:50Z`	`Etc/UTC`
`2023-10-15T13:18:50`	預設為 `Etc/UTC`
`2023-10-15`	預設為 `Etc/UTC`
`15 Oct 2023`	預設為 `Etc/UTC`

最後三個範例並未完全指定，預設會指向 Etc/UTC 時區。

若要覆蓋預設時區，請在你的站點配置中設定 timeZone。確定時區的優先順序如下：

日期/時間字串中的時區偏移量
站點配置中指定的時區
Etc/UTC 時區

Front matter

概覽

欄位

aliases

build

cascade

date

description

draft

expiryDate

headless

isCJKLanguage

keywords

lastmod

layout

linkTitle

markup

menus

modified

outputs

params

pubdate

publishDate

published

resources

sitemap

slug

summary

title

translationKey

type

unpublishdate

url

weight

參數

分類法

繼承

目標特定頁面

path

kind

lang

environment

範例

Emacs Org Mode

日期

延伸閱讀