HUGO 中文文档

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio Star
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可证
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 快速上手
    • 本节内容
    • 快速入门
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 术语表
    • 配置构建
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • Front matter (前置 matter)
    • 构建选项
    • 页面资源
    • 图片处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学公式
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基模板
    • 首页模板
    • 单个模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 内嵌模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • css
    • fmt
    • go 模板
    • hugo
    • js
    • lang
    • openapi3
    • os
    • urls
    • 全局
    • 加密
    • 反射
    • 变形
    • 变换
    • 哈希
    • 图像
    • 图表函数
    • 字符串
    • 安全函数
    • 局部模板函数
    • 数学
    • 数据
    • 时间
    • 模板
    • 比较
    • 类型转换
    • 编码
    • 调试
    • 资源
    • 路径
    • 集合
  • 方法
    • 本节内容
    • Duration
    • Menu
    • Page
    • Pager
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
    • 菜单项
    • 页面
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • Images
    • 链接
    • Passthrough
    • 表格
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo 管道
    • 本节内容
    • 简介
    • 将 Sass 编译为 CSS
    • PostCSS
    • PostProcess
    • JavaScript 构建
    • 资源压缩
    • 连接资产
    • 指纹和 SRI 哈希
    • 从字符串创建资源
    • 从模板创建资源
  • 命令行界面
  • 故障排除
    • 本节内容
    • Audit
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • FAQs
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • Search
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo 部署
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitLab Pages 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
    • 托管在 Azure 静态 Web 应用上
    • 托管在 GitHub Pages 上
    • 托管在 KeyCDN 上
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
CONTENT MANAGEMENT

Front matter (前置 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 ,但您可以使用以下任何字段指定元数据。

以下字段名称是保留的。例如,您不能创建名为 type 的自定义字段。在 params 键下创建自定义字段。有关详细信息,请参阅 参数 部分。

别名

(字符串数组) 一个或多个别名的数组,其中每个别名都是一个相对 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}"。

以上任何一项都可以省略。

对于多语言站点,在站点配置中定义 cascade 值可能更高效,以避免在每种语言的章节、分类法或术语页面上重复 cascade 值。

对于多语言站点,如果您选择在 front matter 中定义 cascade 值,则必须为每种语言创建一个章节、分类法或术语页面; lang 关键字将被忽略。

示例

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 。确定时区的优先级顺序为:

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

See also

  • 配置
  • URL 管理
  • 原型
  • 术语表
  • Passthrough

On this page

  • 概述
  • 字段
  • 参数
  • 分类法
  • 级联
  • Emacs Org 模式
  • 日期
Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays
 

Hugo Sponsors

Your Company?
 

The Hugo logos are copyright © Steve Francia 2013–2025.

The Hugo Gopher is based on an original work by Renée French.

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 快速上手
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • Hugo 模块
  • Hugo 管道
  • 命令行界面
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护