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