前置元数据

前置元数据（front matter）是每个内容文件顶部的一段元数据，用来描述内容、补充内容、建立与其他内容的关系、控制站点的发布结构，并决定 Hugo 选用哪个模板。它用 JSON、TOML 或 YAML 之一序列化，Hugo 通过分隔前置元数据与正文的定界符来判断用的是哪一种。

三种写法

TOML 使用一对 +++：

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

YAML 使用一对 ---：

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

JSON 使用一对花括号：

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

前置元数据字段可以是布尔值、整数、浮点数、字符串、数组或映射。注意 TOML 还支持不加引号的日期时间值。同一个文件里不要混用两种定界符，整个站点也建议统一。

字段

最常用的字段是 date、draft、title 和 weight，其余可用字段见下表。

注意：上表中的字段名是保留的，例如不能创建名为 type 的自定义字段，自定义字段要写在 params 键下。

sites 字段的配置示例如下（示例文件为 content/_index.md）：

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

从模板读取这些值时，使用 Page 对象上「模板取值方法」一列给出的方法，例如 .Title、.Date、.Params。

自定义参数

在 params 键下指定自定义页面参数：

+++
title = '示例'
date = 2024-02-02T04:14:54-08:00
[params]
author = 'John Smith'
+++

模板中通过 Page 对象的 .Params 或 .Param 方法读取。.Param 先在页面参数中查找，找不到时回退到站点参数。

分类法

在配置中声明分类法，例如：

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

然后在前置元数据里按复数形式写入术语：

+++
title = '示例'
tags = ['red','blue']
genres = ['mystery','romance']
+++

可以给这些页面种类（page kind）添加分类法术语：home、page、section、taxonomy、term。模板中用 .Params 或 .GetTerms 读取，例如：

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

级联

级联（cascade）把前置元数据中的值向下传递给后代页面，除非被后代自身或更近的祖先覆盖。多语言项目更适合在项目配置中定义级联值，可以避免为每种语言重复书写。

例如，把 color 页面参数从首页级联给全部后代：

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

目标

cascade.target 接受一个页面匹配器（page matcher），把级联值限制在部分页面上¹；不指定 target 时，值级联给全部后代页面。匹配器支持的关键字有：environment（构建环境的 glob 模式）、kind（页面种类的 glob 模式）、path（页面逻辑路径的 glob 模式）、sites（自 0.153.0 起，匹配语言、版本、角色等内容维度的 sites matrix）；lang 自 0.153.0 起废弃，请改用 sites。

[cascade.params]
color = 'red'
[cascade.target]
path = '{/articles,/articles/**}'

切片

用级联映射数组可以给不同目标设置不同值：

+++
title = 'Home'
[[cascade]]
[cascade.params]
color = 'red'
[cascade.target]
path = '{/articles,/articles/**}'
[[cascade]]
[cascade.params]
color = 'blue'
[cascade.target]
path = '{/tutorials,/tutorials/**}'
+++

Emacs Org Mode 写法

内容格式为 Emacs Org Mode 时，可以用 Org Mode 关键字提供前置元数据：

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

日期

无论是自定义页面参数，还是四个预定义的日期字段（date、expiryDate、lastmod、publishDate），都应使用下列可解析格式之一：

后三种不是完整限定格式，时区默认为 Etc/UTC。要覆盖默认时区，在项目配置中设置 timeZone；时区的判定优先级依次为：日期时间字符串里的时区偏移、项目配置中指定的时区、Etc/UTC。

日期的回退顺序

Page 对象上有四个返回日期的方法：Date、ExpiryDate、Lastmod、PublishDate。Hugo 依据项目配置中 [frontmatter] 区段的设置决定它们的取值顺序。例如 ExpiryDate 方法在 expirydate 存在时返回该值，否则返回 unpublishdate。

[frontmatter]
date = ["myDate", "date"]

上例中，Date 方法在 myDate 存在时返回它，否则返回 date。要让列表回退到默认的日期序列，使用 :default 记号：

[frontmatter]
date = ["myDate", ":default"]

此时若 myDate 不存在，则取 date、publishdate、pubdate、published、lastmod、modified 中第一个有效日期。可用的记号还有：

• :fileModTime：文件的最后修改时间戳。
• :filename：从文件名开头提取日期，支持 YYYY-MM-DD 以及 YYYY-MM-DD-HH-MM-SS（自 0.148.0 起）两种形式，日期与时间之间可以用任意字符分隔（例如 2025-02-01T14-30-00）。仅当 :filename 是最终生效的日期来源时，Hugo 才会从剩余文件名推导页面的 slug；若页面前置元数据中已经定义了 slug，则不再推导。例如文件名为 2025-02-01-article.md 时，日期为 2025-02-01，slug 为 article。
• :git：文件最后一次修订的 Git 作者日期，需要把 enableGitInfo 设为 true。

默认的日期字段别名是：expiryDate ← unpublishdate，lastmod ← modified，publishDate ← pubdate、published。

书写建议

• 只写需要的字段；自定义参数尽量放进 params 表，避免与保留字段重名。
• 若希望排序与显示稳定可预期，最好显式写出 date，需要时再写 lastmod。
• draft、publishDate、expiryDate、cascade、build 等字段会直接改变输出结果，改动后请重新构建确认。
• 页面包中的 index.md 与 _index.md 同样使用前置元数据，headless 等字段见页面包。