前言 | Hugo 框架

概述

每个内容文件顶部的“前言”是元数据，它：

描述内容
增强内容
建立与其他内容的关系
控制您网站的发布结构
确定模板选择

使用序列化格式提供前言，包括 JSON、TOML 或 YAML。 Hugo 通过检查将前言与页面内容分隔开的定界符来确定前言格式。

通过在下面的序列化格式之间切换，查看前言定界符的示例。

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
}

前言字段可以是布尔值、整数、浮点数、字符串、数组或映射。请注意，TOML 格式还支持不带引号的日期/时间值。

字段

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

aliases

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

build

（映射）构建选项的映射。

cascade

（映射）前言键的映射，其值将传递给页面的后代，除非被自身或更近的祖先的级联覆盖。有关详细信息，请参阅级联部分。

date

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

description

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

draft

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

expiryDate

(string) 页面过期日期。在过期日期当天或之后，除非您向 hugo 命令传递 --buildExpired 标志，否则该页面将不会被渲染。请注意，TOML 格式也支持不带引号的日期/时间值。有关示例，请参阅日期部分。使用 Page 对象的 ExpiryDate 方法从模板访问此值。

headless

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

isCJKLanguage

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

keywords

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

lastmod

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

layout

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

linkTitle

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

markup

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

menus

(string、string array 或 map) 如果设置，Hugo 会将页面添加到给定的菜单或多个菜单中。有关详细信息，请参阅菜单页面。

modified

别名，指向 lastmod。

outputs

(string array) 要渲染的输出格式。

params

v0.123.0 中的新功能

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

pubdate

别名，指向 publishDate。

publishDate

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

published

别名，指向 publishDate。

resources

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

sitemap

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

slug

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

summary

(string) 在概念上与页面 description 不同，摘要要么总结内容，要么充当预告片以鼓励读者访问该页面。使用 Page 对象的 Summary 方法从模板访问此值。

title

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

translationKey

(string) 用于关联同一页面的两个或多个翻译的任意值，当翻译后的页面不共享公共路径时很有用。使用 Page 对象的 TranslationKey 方法从模板访问此值。

type

(string) 内容类型，覆盖从页面所在的顶层节派生的值。使用 Page 对象的 Type 方法从模板访问此值。

unpublishdate

是 expirydate 的别名。

url

（string）覆盖整个 URL 路径。适用于常规页面和节页面。有关详细信息，请参阅 URL 管理页面。

weight

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

参数

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>Tags</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: Home
---

+++
title = 'Home'
[[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": "Home"
}

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

path

（string）一个Glob模式，匹配 /content 下面的内容路径。预期使用 Unix 样式的斜杠。请注意，这是虚拟路径，因此它从挂载根开始。匹配支持双星号，因此您可以匹配诸如 /blog/*/** 之类的模式，以匹配从第三级及以下的所有内容。

kind

（string）一个 Glob 模式，匹配页面的 Kind，例如 “{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: Posts
---

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

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

在上面的示例中，当调用 .Params.banner 时，posts 节页面及其后代将返回 images/typewriter.jpg，除非

该后代具有自己的 banner 值设置
或者，更近的祖先节点具有自己的 cascade.banner 值设置。

Emacs Org 模式

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

content/example.org

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

请注意，您还可以在一行上指定数组元素

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`
`2023 年 10 月 15 日`	默认为 `Etc/UTC`

最后三个示例不是完全限定的，并且默认为 Etc/UTC 时区。

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

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

概述

字段

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 模式

日期

另请参阅

上次更新时间：2024 年 11 月 4 日：使用新的注释短代码替换 markdown 中的 HTML 注释 (b5f289165)