Front matter (前置 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: 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 字段可以是布尔值、整数、浮点数、字符串、数组或映射。请注意，TOML 格式还支持未加引号的日期/时间值。

字段

最常见的 front matter 字段是 date 、 draft 、 title 和 weight ，但您可以使用以下任何字段指定元数据。

别名

(字符串数组) 一个或多个别名的数组，其中每个别名都是一个相对 URL，它将把浏览器重定向到当前位置。使用 Page 对象上的 Aliases 方法从模板访问这些值。有关详细信息，请参阅别名部分。

构建

(映射) 构建选项的映射。

级联

(映射) front matter 键的映射，其值传递给页面的子代，除非被自身或更近的祖先的级联覆盖。有关详细信息，请参阅级联部分。

日期

(字符串) 与页面关联的日期，通常是创建日期。请注意，TOML 格式还支持未加引号的日期/时间值。有关示例，请参阅日期部分。使用 Page 对象上的 Date 方法从模板访问此值。

描述

(字符串) 从概念上不同于页面 summary ，描述通常在已发布 HTML 文件的 head 元素内的 meta 元素中呈现。使用 Page 对象上的 Description 方法从模板访问此值。

草稿

(布尔值) 如果为 true ，除非您将 --buildDrafts 标志传递给 hugo 命令，否则不会呈现该页面。使用 Page 对象上的 Draft 方法从模板访问此值。

过期日期

(字符串) 页面的过期日期。在过期日期或之后，除非您将 --buildExpired 标志传递给 hugo 命令，否则不会呈现该页面。请注意，TOML 格式还支持未加引号的日期/时间值。有关示例，请参阅日期部分。使用 Page 对象上的 ExpiryDate 方法从模板访问此值。

无头

(布尔值) 适用于叶子包，如果为 true ，则此值将 render 和 list 构建选项设置为 never ，从而创建页面资源的无头包。

是否 CJK 语言

(布尔值) 如果内容语言属于 CJK 族，则设置为 true 。此值决定 Hugo 如何计算字数，并影响 Page 对象上的 WordCount、FuzzyWordCount、ReadingTime 和 Summary 方法返回的值。

关键词

(字符串数组) 关键词数组，通常在已发布 HTML 文件的 head 元素内的 meta 元素中呈现，或用作分类法来对内容进行分类。使用 Page 对象上的 Keywords 方法从模板访问这些值。

最后修改时间

(字符串) 页面上次修改的日期。请注意，TOML 格式还支持未加引号的日期/时间值。有关示例，请参阅日期部分。使用 Page 对象上的 Lastmod 方法从模板访问此值。

布局

(字符串) 提供模板名称以定位特定模板，覆盖默认的模板查找顺序。将值设置为模板的基本文件名，不包括其扩展名。使用 Page 对象上的 Layout 方法从模板访问此值。

链接标题

(字符串) 通常是 title 的较短版本。使用 Page 对象上的 LinkTitle 方法从模板访问此值。

标记

(字符串) 与受支持的内容格式之一相对应的标识符。如果未提供，Hugo 会根据文件扩展名确定内容渲染器。

菜单

(字符串 、 字符串数组 或 映射) 如果设置，Hugo 会将页面添加到给定的菜单或菜单中。有关详细信息，请参阅菜单页面。

修改时间

lastmod 的别名。

输出

(字符串数组) 要呈现的输出格式。

参数

New in v0.123.0

(映射) 自定义页面参数的映射。

发布日期

publishDate 的别名。

发布日期

(字符串) 页面的发布时间。在发布时间之前，除非您将 --buildFuture 标志传递给 hugo 命令，否则不会呈现该页面。请注意，TOML 格式还支持未加引号的日期/时间值。有关示例，请参阅日期部分。使用 Page 对象上的 PublishDate 方法从模板访问此值。

已发布

publishDate 的别名。

资源

(映射数组) 映射数组，用于提供页面资源的元数据。

站点地图

(映射) 站点地图选项的映射。有关详细信息，请参阅站点地图模板页面。使用 Page 对象上的 Sitemap 方法从模板访问这些值。

标识

(字符串) 覆盖 URL 路径的最后一部分。不适用于章节页面。有关详细信息，请参阅 URL 管理页面。使用 Page 对象上的 Slug 方法从模板访问此值。

摘要

(字符串) 从概念上不同于页面 description ，摘要要么总结内容，要么作为预告来鼓励读者访问页面。使用 Page 对象上的 Summary 方法从模板访问此值。

标题

(字符串) 页面标题。使用 Page 对象上的 Title 方法从模板访问此值。

翻译键

(字符串) 用于关联同一页面的两个或多个翻译的任意值，在翻译页面没有共享公共路径时非常有用。使用 Page 对象上的 TranslationKey 方法从模板访问此值。

类型

(字符串) 内容类型，覆盖从页面所在的顶级部分派生的值。使用 Page 对象上的 Type 方法从模板访问此值。

取消发布日期

expirydate 的别名。

url

(字符串) 覆盖整个 URL 路径。适用于常规页面和章节页面。有关详细信息，请参阅 URL 管理页面。

权重

(整数) 页面的权重，用于在页面集合中对页面进行排序。使用 Page 对象上的 Weight 方法从模板访问此值。

参数

New in v0.123.0

在 front matter 中的 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
}

使用 Page 对象上的 Params 或 Param 方法从模板访问这些值。

Hugo 提供嵌入式模板可选地在渲染页面的 head 元素中插入元数据。这些嵌入式模板需要以下 front matter 参数：

参数	数据类型	用于以下嵌入式模板
`audio`	`[]string`	`opengraph.html`
`images`	`[]string`	`opengraph.html` , `schema.html` , `twitter_cards.html`
`videos`	`[]string`	`opengraph.html`

如果 front matter 中未提供参数，嵌入式模板将跳过该参数，但如果数据类型意外，则会引发错误。

分类法

通过向 front matter 添加分类术语来对内容进行分类。例如，使用此站点配置：

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
}

您可以将分类术语添加到任何这些 [页面类型] 的 front matter 中：

home
page
section
taxonomy
term

使用 Page 对象上的 Params 或 GetTerms 方法从模板访问分类术语。例如：

layouts/_default/single.html

{{ with .GetTerms "tags" }}

  <p>标签</p>
  <ul>
    {{ range . }}
      <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
    {{ end }}
  </ul>
{{ end }}

级联

任何节点都可以将其 front matter 值集传递给其子代。

定位特定页面

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": "主页"
}

使用这些关键字的任何组合来定位一组页面：

路径

(字符串) 与 /content 下的内容路径匹配的 Glob 模式。需要使用 Unix 风格的斜杠。请注意，这是虚拟路径，因此它从挂载根目录开始。匹配支持双星号，因此您可以匹配 /blog/*/** 等模式以匹配从第三层及以下的任何内容。

类型

(字符串) 与页面的类型匹配的 Glob 模式，例如 “{home,section}"。

语言

(字符串) 与页面的语言匹配的 Glob 模式，例如 “{en,sv}"。

环境

(字符串) 与构建环境匹配的 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": "文章"
}

使用上述示例，除非：

指定的子代已设置其自身的 banner 值
或者更近的祖先节点已设置其自身的 cascade.banner 值。

文章章节页面及其子代在调用 .Params.banner 时将返回 images/typewriter.jpg 。

Emacs Org 模式

如果您的内容格式是 [Emacs Org 模式]，您可以使用 Org 模式关键字提供 front matter。例如：

content/example.org

# +TITLE: Example {#title-example}

# +DATE: 2024-02-02T04:14:54-08:00 {#date-2024-02-02t04-14-54-08-00}

# +DRAFT: false {#draft-false}

# +AUTHOR: John Smith {#author-john-smith}

# +GENRES: mystery {#genres-mystery}

# +GENRES: romance {#genres-romance}

# +TAGS: red {#tags-red}

# +TAGS: blue {#tags-blue}

# +WEIGHT: 10 {#weight-10}

请注意，您也可以在一行中指定数组元素：

content/example.org

# +TAGS[]: red blue {#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`
`2023年10月15日`	默认为 `Etc/UTC`

最后三个例子没有完全限定，默认为 Etc/UTC 时区。

要覆盖默认时区，请在站点配置中设置 timeZone 。确定时区的优先级顺序为：

日期/时间字符串中的时区偏移量
在站点配置中指定的时区
Etc/UTC 时区

概述

字段

别名

构建

级联

日期

描述

草稿

过期日期

无头

是否 CJK 语言

关键词

最后修改时间

布局

链接标题

标记

菜单

修改时间

输出

参数

发布日期

发布日期

已发布

资源

站点地图

标识

摘要

标题

翻译键

类型

取消发布日期

url

权重

参数

分类法

级联

定位特定页面

路径

类型

语言

环境

示例

Emacs Org 模式

日期

See also

Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)