Hugo Front Matter

概述

每個內容文件頂部的 front matter 是元數據，用於：

• 描述內容
• 增強內容
• 建立與其他內容的關系
• 控制站點的發布結構
• 確定模板選擇

使用序列化格式（JSON、TOML 或 YAML 之一）提供 front matter。Hugo 通過檢查分隔 front matter 和頁面內容的分隔符來確定 front matter 格式。

切換下面的序列化格式查看 front matter 分隔符示例。

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

Front matter 字段可以是 boolean、integer、float、string、arrays 或 maps。請注意，TOML 格式還支持未加引號的日期/時間值。

字段

最常見的 front matter 字段是 date、draft、title 和 weight，但你可以使用下面的任何字段指定元數據。

aliases

([]string) 一個或多個 page-relative 或 site-relative 路徑的數組，這些路徑應重定向到當前頁面。Hugo 在構建過程中將這些解析為 server-relative URL。使用 Page 對象上的 Aliases 方法從模板訪問這些值。有關詳細信息，請參閱 aliases 部分。

build

(map) build options 映射。

cascade

(map) front matter 鍵的映射（或映射切片），其值傳遞給頁面的後代，除非被自身或更近的祖先的 cascade 覆蓋。有關詳細信息，請參閱 cascade 部分。

date

(string) 與頁面關聯的日期，通常是創建日期。請注意，TOML 格式還支持未加引號的日期/時間值。有關示例，請參閱 dates 部分。使用 Page 對象上的 Date 方法從模板訪問此值。

description

(string) 與頁面 summary 概念上不同，描述通常在已發布 HTML 文件的 head 元素中的 meta 元素內渲染。使用 Page 對象上的 Description 方法從模板訪問此值。

draft

(bool) 是否禁用渲染，除非你將 --buildDrafts 標志傳遞給 hugo 命令。使用 Page 對象上的 Draft 方法從模板訪問此值。

expiryDate

(string) 頁面失效日期。在失效日期或之後，除非你將 --buildExpired 標志傳遞給 hugo 命令，否則不會渲染頁面。請注意，TOML 格式還支持未加引號的日期/時間值。有關示例，請參閱 dates 部分。使用 Page 對象上的 ExpiryDate 方法從模板訪問此值。

headless

(bool) 適用於 leaf bundles，是否將 render 和 list build options 設置為 never，創建無頭的 page resources bundle。

isCJKLanguage

(bool) 內容語言是否屬於 CJK 家族。此值決定 Hugo 如何計算字數，並影響 Page 對象上的 WordCount、FuzzyWordCount、ReadingTime 和 Summary 方法返回的值。

keywords

([]string) 關鍵字數組，通常在已發布 HTML 文件的 head 元素中的 meta 元素內渲染，或用作 taxonomy 對內容進行分類。使用 Page 對象上的 Keywords 方法從模板訪問這些值。

lastmod

(string) 頁面最後修改的日期。請注意，TOML 格式還支持未加引號的日期/時間值。有關示例，請參閱 dates 部分。使用 Page 對象上的 Lastmod 方法從模板訪問此值。

layout

(string) 提供模板名稱以 target a specific template，覆蓋默認 template lookup order。將值設置為模板的基本文件名，不包括其擴展名。使用 Page 對象上的 Layout 方法從模板訪問此值。

linkTitle

(string) 通常比 title 短的版本。使用 Page 對象上的 LinkTitle 方法從模板訪問此值。

markup

(string) 對應於支持的 content formats 之一的標識符。如果未提供，Hugo 根據文件擴展名確定內容渲染器。

menus

(string、[]string 或 map) 如果設置，Hugo 將頁面添加到給定菜單。有關詳細信息，請參閱 menus 頁面。

modified

lastmod 的別名。

outputs

([]string) 要渲染的 output formats。有關更多信息，請參閱 configure outputs。

params

(map) 自定義 page parameters 映射。

pubdate

publishDate 的別名。

publishDate

(string) 頁面發布日期。在發布日期之前，除非你將 --buildFuture 標志傳遞給 hugo 命令，否則不會渲染頁面。請注意，TOML 格式還支持未加引號的日期/時間值。有關示例，請參閱 dates 部分。使用 Page 對象上的 PublishDate 方法從模板訪問此值。

published

publishDate 的別名。

resources

(map array) 為 page resources 提供元數據的映射數組。

sitemap

(map) sitemap 選項映射。有關詳細信息，請參閱 sitemap templates 頁面。使用 Page 對象上的 Sitemap 方法從模板訪問這些值。

sites

New in v0.153.0

(map) 定義頁面的 sites matrix 和 sites complements 的映射。

---
sites:
  complements:
    versions:
    - v3.*.*
  matrix:
    languages:
    - en
    - fr
    roles:
    - '**'
    versions:
    - v1.2.*
    - v2.*.*
title: Home
---

+++
title = 'Home'
[sites]
  [sites.complements]
    versions = ['v3.*.*']
  [sites.matrix]
    languages = ['en', 'fr']
    roles = ['**']
    versions = ['v1.2.*', 'v2.*.*']
+++

{
   "sites": {
      "complements": {
         "versions": [
            "v3.*.*"
         ]
      },
      "matrix": {
         "languages": [
            "en",
            "fr"
         ],
         "roles": [
            "**"
         ],
         "versions": [
            "v1.2.*",
            "v2.*.*"
         ]
      }
   },
   "title": "Home"
}

slug

(string) 覆蓋 URL 路徑的最後一段。不適用於 home、section、taxonomy 或 term 頁面。有關詳細信息，請參閱 URL management 頁面。使用 Page 對象上的 Slug 方法從模板訪問此值。

summary

(string) 與頁面 description 概念上不同，summary 要麼總結內容，要麼作為誘餌鼓勵讀者訪問頁面。使用 Page 對象上的 Summary 方法從模板訪問此值。

title

(string) 頁面標題。使用 Page 對象上的 Title 方法從模板訪問此值。

translationKey

(string) 用於關聯同一頁面的兩個或多個翻譯的任意值，當翻譯頁面不共享公共路徑時很有用。使用 Page 對象上的 TranslationKey 方法從模板訪問此值。

type

(string) content type，覆蓋從頁面駐留的頂層 section 派生的值。使用 Page 對象上的 Type 方法從模板訪問此值。

unpublishdate

expirydate 的別名。

url

(string) 覆蓋整個 URL 路徑。適用於常規頁面和 section 頁面。有關詳細信息，請參閱 URL management 頁面。

weight

(int) 頁面 weight，用於在 page collection 中對頁面排序。使用 Page 對象上的 Weight 方法從模板訪問此值。

Parameters

在 front matter 的 params 鍵下指定自定義頁面參數：

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

使用 Page 對象上的 Params 或 Param 方法從模板訪問這些值。

Hugo 提供 embedded templates 以選擇性地在渲染頁面的 head 元素中插入元數據。這些嵌入式模板期望以下 front matter 參數：

如果 front matter 中未提供參數，嵌入式模板將跳過該參數，但如果數據類型意外則會拋出錯誤。

Taxonomies

通過將分類術語添加到 front matter 來對內容進行分類。例如，使用此站點配置：

taxonomies:
  genre: genres
  tag: tags

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

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

添加分類術語，如下所示：

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

你可以將分類術語添加到任何這些 page kinds 的 front matter 中：

• home
• page
• section
• taxonomy
• term

使用 Page 對象上的 Params 或 GetTerms 方法從模板訪問分類術語。例如：

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

Cascade

node 可以將 front matter 值級聯到其後代。但是，如果後代已經定義了該字段，或者如果更近的祖先節點已經為該字段級聯了值，則此級聯將被阻止。

例如，從首頁向所有後代級聯"color"參數：

---
cascade:
  params:
    color: red
title: Home
---

+++
title = 'Home'
[cascade]
  [cascade.params]
    color = 'red'
+++

{
   "cascade": {
      "params": {
         "color": "red"
      }
   },
   "title": "Home"
}

New in v0.153.0 從 Hugo 0.153.0 開始，你還可以將 sites front matter 設置為 cascade front matter 值，這意味著你可以例如將一個或多個語言應用於 target 頁面。

Target

target¹ 關鍵字允許你定位特定頁面或 environments。例如，僅從首頁向"articles"section 內的頁面（包括"articles"section 頁面本身）級聯"color"參數：

---
cascade:
  params:
    color: red
  target:
    path: '{/articles,/articles/**}'
    sites:
      matrix:
        languages:
        - en
        - fr
title: Home
---

+++
title = 'Home'
[cascade]
  [cascade.params]
    color = 'red'
  [cascade.target]
    path = '{/articles,/articles/**}'
    [cascade.target.sites]
      [cascade.target.sites.matrix]
        languages = ['en', 'fr']
+++

{
   "cascade": {
      "params": {
         "color": "red"
      },
      "target": {
         "path": "{/articles,/articles/**}",
         "sites": {
            "matrix": {
               "languages": [
                  "en",
                  "fr"
               ]
            }
         }
      }
   },
   "title": "Home"
}

使用這些關鍵字的任何組合來定位頁面和/或環境：

environment

(string) 匹配構建 environment 的 glob pattern。例如：{staging,production}。

kind

(string) 匹配 page kind 的 glob pattern。例如：{taxonomy,term}。

path

(string) 匹配頁面 logical path 的 glob pattern。例如：{/books,/books/**}。

sites

New in v0.153.0

(map) 定義 target 的 sites matrix 的映射，即：哪些站點應該接收級聯值。

Array

定義級聯參數數組以將不同值應用於不同 target。例如：

---
cascade:
- params:
    color: red
  target:
    kind: page
    path: '{/books/**}'
- params:
    color: blue
  target:
    kind: page
    path: '{/films/**}'
title: Home
---

+++
title = 'Home'
[[cascade]]
  [cascade.params]
    color = 'red'
  [cascade.target]
    kind = 'page'
    path = '{/books/**}'
[[cascade]]
  [cascade.params]
    color = 'blue'
  [cascade.target]
    kind = 'page'
    path = '{/films/**}'
+++

{
   "cascade": [
      {
         "params": {
            "color": "red"
         },
         "target": {
            "kind": "page",
            "path": "{/books/**}"
         }
      },
      {
         "params": {
            "color": "blue"
         },
         "target": {
            "kind": "page",
            "path": "{/films/**}"
         }
      }
   ],
   "title": "Home"
}

Emacs Org Mode

如果你的 content format 是 Emacs Org Mode，你可以使用 Org Mode 關鍵字提供 front matter。例如：

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

請注意，你也可以在一行上指定數組元素：

#+TAGS[]: red blue

Dates

填充日期字段時，無論是 custom page parameter 還是四個預定義字段之一（date、expiryDate、lastmod、publishDate），請使用以下可解析格式之一：

最後三個示例不是完全限定的，默認為 Etc/UTC 時區。

要覆蓋默認時區，在站點配置中設置 timeZone。確定時區的優先級順序為：

1. 日期/時間字符串中的時區偏移
2. 站點配置中指定的時區
3. Etc/UTC 時區