前言
概述
每个内容文件顶部的“前言”是元数据,它:
- 描述内容
- 增强内容
- 建立与其他内容的关系
- 控制您网站的发布结构
- 确定模板选择
使用序列化格式提供前言,包括 JSON、TOML 或 YAML。 Hugo 通过检查将前言与页面内容分隔开的定界符来确定前言格式。
通过在下面的序列化格式之间切换,查看前言定界符的示例。
---
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
键下指定自定义页面参数
---
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 中添加分类术语来对内容进行分类。例如,使用以下站点配置
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
}
您可以将分类术语添加到以下任何页面类型的 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 }}
级联
任何节点都可以将其 front matter 值传递给其后代。
定位特定页面
cascade
块可以是一个数组,其中包含一个可选的 _target
关键字,允许您在级联值时定位不同的页面集。
---
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}”
以上任何一个都可以省略。
示例
---
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。例如
#+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
),请使用以下可解析的格式之一
格式 | 时区 |
---|---|
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
时区