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 上
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
TEMPLATES FUNDAMENTALS

模板入门

创建模板以渲染你的内容、资源和数据。

模板是项目、主题或模块的 layouts 目录中的一个文件。模板使用 变量 、 函数 和 方法 将你的内容、资源和数据转换为已发布的页面。

Hugo 使用 Go 的 text/template 和 html/template 包。

text/template 包实现了用于生成文本输出的数据驱动模板,而 html/template 包实现了用于生成 HTML 输出的数据驱动模板,安全地防止代码注入。

默认情况下,Hugo 在渲染 HTML 文件时使用 html/template 包。

例如,此 HTML 模板初始化 $v1 和 $v2 变量,然后在 HTML 段落中显示它们及其乘积。

{{ $v1 := 6 }}
{{ $v2 := 7 }}
<p>The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.</p>

虽然 HTML 模板最为常见,但你可以为任何 输出格式 创建模板,包括 CSV、JSON、RSS 和纯文本。

上下文

在创建模板之前,需要理解的最重要的概念是 上下文 ,即传递到每个模板中的数据。数据可以是简单值,或者更常见的是 对象 和相关的 方法 。

例如,单个页面的模板接收一个 Page 对象, Page 对象提供方法来返回值或执行操作。

当前上下文

在模板中,点 (.) 代表当前上下文。

layouts/_default/single.html
<h2>{{ .Title }}</h2>

在上面的示例中,点代表 Page 对象,我们调用它的 Title 方法来返回在 前置内容 中定义的标题。

当前上下文可能会在模板中发生更改。例如,在模板顶部,上下文可能是一个 Page 对象,但我们在 range 或 with 块中将上下文重新绑定到另一个值或对象。

layouts/_default/single.html
<h2>{{ .Title }}</h2>

{{ range slice "foo" "bar" }}

  <p>{{ . }}</p>
{{ end }}

{{ with "baz" }}

  <p>{{ . }}</p>
{{ end }}

在上面的示例中,当我们遍历值的 切片 时,上下文会发生变化。在第一次迭代中,上下文是“foo”,在第二次迭代中,上下文是“bar”。在 with 块内,上下文是“baz”。Hugo 将以上内容渲染为:

<h2>My Page Title</h2>
<p>foo</p>
<p>bar</p>
<p>baz</p>

模板上下文

在 range 或 with 块中,可以通过在点前面添加美元符号 ($) 来访问传递到模板的上下文:

layouts/_default/single.html
{{ with "foo" }}

  <p>{{ $.Title }} - {{ . }}</p>
{{ end }}

Hugo 将其渲染为:

<p>My Page Title - foo</p>

在继续阅读之前,请确保你完全理解 上下文 的概念。新用户犯下的最常见的模板错误与上下文有关。

操作

在上面的示例中,成对的左大括号和右大括号表示模板操作的开始和结束,即模板中的数据评估或控制结构。

模板操作可以包含文字值( 布尔值 、 字符串 、 整数 和 浮点数 )、变量、函数和方法。

layouts/_default/single.html
{{ $convertToLower := true }}
{{ if $convertToLower }}

  <h2>{{ strings.ToLower .Title }}</h2>
{{ end }}

在上面的示例中:

  • $convertToLower 是一个变量
  • true 是一个文字布尔值
  • strings.ToLower 是一个将所有字符转换为小写的函数
  • Title 是 Page 对象上的一个方法

Hugo 将以上内容渲染为:

<h2>my page title</h2>

空格

注意前面示例中的空行和缩进?尽管在生产环境中(你通常会最小化输出)无关紧要,但你可以使用带有连字符的模板操作分隔符来删除相邻的空格:

layouts/_default/single.html
{{- $convertToLower := true -}}
{{- if $convertToLower -}}

  <h2>{{ strings.ToLower .Title }}</h2>
{{- end -}}

Hugo 将其渲染为:

<h2>my page title</h2>

空格包括空格、水平制表符、回车符和换行符。

管道

在模板操作中,你可以将值 管道 到函数或方法。管道值成为函数或方法的最终参数。例如,这些是等效的:

{{ strings.ToLower "Hugo" }} → hugo
{{ "Hugo" | strings.ToLower }} → hugo

你可以将一个函数或方法的结果管道到另一个函数或方法。例如,这些是等效的:

{{ strings.TrimSuffix "o" (strings.ToLower "Hugo") }} → hug
{{ "Hugo" | strings.ToLower | strings.TrimSuffix "o" }} → hug

这些也是等效的:

{{ mul 6 (add 2 5) }} → 42
{{ 5 | add 2 | mul 6 }} → 42

请记住,管道值成为你正在进行管道的函数或方法的最终参数。

分行

你可以将模板操作分成两行或多行。例如,这些是等效的:

{{ $v := or $arg1 $arg2 }}

{{ $v := or
  $arg1
  $arg2
}}

你还可以将 原始字符串文字 分成两行或多行。例如,这些是等效的:

{{ $msg := "This is line one.\nThis is line two." }}

{{ $msg := `This is line one.
This is line two.`
}}

变量

变量是用美元符号 ($) 开头的用户定义的 标识符 ,表示任何数据类型的值,在模板操作中初始化或赋值。例如, $foo 和 $bar 是变量。

变量可以包含 标量 、 切片 、 映射 或 对象 。

使用 := 初始化变量,使用 = 为已初始化的变量赋值。例如:

{{ $total := 3 }}
{{ range slice 7 11 21 }}
  {{ $total = add $total . }}
{{ end }}
{{ $total }} → 42

在 if 、 range 或 with 块内初始化的变量的作用域限于该块。在这些块之外初始化的变量的作用域限于模板。

对于表示切片或映射的变量,使用 index 函数返回所需的值。

{{ $slice := slice "foo" "bar" "baz" }}
{{ index $slice 2 }} → baz

{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
{{ index $map "c" }} → baz

切片和数组都是从零开始的;元素 0 是第一个元素。

对于表示映射或对象的变量, 链接 标识符以返回所需的值或访问所需的方法。

{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
{{ $map.c }} → baz

{{ $homePage := .Site.Home }}
{{ $homePage.Title }} → My Homepage

如上所示,对象和方法名称都是大写的。虽然不是必需的,但为了避免混淆,我们建议变量和映射键名称以小写字母或下划线开头。

函数

函数在模板操作中使用,它接受一个或多个参数并返回值。与方法不同,函数不与对象关联。

Go 的 text/template 和 html/template 包提供少量函数、运算符和语句供一般使用。有关详细信息,请参阅函数文档的 go-templates 部分。

Hugo 提供数百个按命名空间分类的自定义 函数 。例如, strings 命名空间包含这些函数和其他函数:

函数 别名
strings.ToLower lower
strings.ToUpper upper
strings.Replace replace

如上所示,常用函数都有一个别名。在模板中使用别名以减少代码长度。

调用函数时,用空格将参数与函数分开,并将参数彼此分开。例如:

{{ $total := add 1 2 3 4 }}

方法

方法在模板操作中使用,并与对象关联,它接受零个或多个参数,并返回一个值或执行一个操作。

最常访问的对象是 Page 和 Site 对象。这是每个对象可用的 方法 的一小部分示例。

对象 方法 描述
Page Date 返回给定页面的日期。
Page Params 返回给定页面前置内容中定义的自定义参数映射。
Page Title 返回给定页面的标题。
Site Data 返回由 data 目录中的文件组成的结构。
Site Params 返回在站点配置中定义的自定义参数映射。
Site Title 返回在站点配置中定义的标题。

用点 (.) 将方法链接到其对象,如下所示,记住前导点表示 当前上下文 。

layouts/_default/single.html
{{ .Site.Title }} → My Site Title
{{ .Page.Title }} → My Page Title

传递到大多数模板的上下文是一个 Page 对象,因此这与前面的示例等效:

layouts/_default/single.html
{{ .Site.Title }} → My Site Title
{{ .Title }} → My Page Title

有些方法需要参数。用空格将参数与方法分开。例如:

layouts/_default/single.html
{{ $page := .Page.GetPage "/books/les-miserables" }}
{{ $page.Title }} → 《悲惨世界》

注释

不要尝试使用 HTML 注释分隔符来注释掉模板代码。

Hugo 在渲染页面时会删除 HTML 注释,但首先会评估 HTML 注释分隔符内的任何模板代码。根据 HTML 注释分隔符内的模板代码,这可能会导致意外结果或构建失败。

模板注释类似于模板操作。成对的左大括号和右大括号表示注释的开始和结束。例如:

{{/* This is an inline comment. */}}
{{- /* This is an inline comment with adjacent whitespace removed. */ -}}

注释中的代码不会被解析、执行或显示。注释可以是内联的(如上所示),也可以是块形式的:

{{/*
This is a block comment.
*/}}

{{- /*
This is a block comment with
adjacent whitespace removed.
*/ -}}

你不能将一个注释嵌套在另一个注释中。

要渲染 HTML 注释,请通过 safeHTML 模板函数传递字符串。例如:

{{ "<!-- I am an HTML comment. -->" | safeHTML }}
{{ printf "<!-- This is the %s site. -->" .Site.Title | safeHTML }}

包含

使用 template 函数包含一个或多个 Hugo 的[嵌入式模板]:

{{ template "_internal/google_analytics.html" . }}
{{ template "_internal/opengraph" . }}
{{ template "_internal/pagination.html" . }}
{{ template "_internal/schema.html" . }}
{{ template "_internal/twitter_cards.html" . }}

使用 partial 或 partialCached 函数包含一个或多个[局部模板]:

{{ partial "breadcrumbs.html" . }}
{{ partialCached "css.html" . }}

在 layouts/partials 目录中创建你的局部模板。

在上面的示例中,请注意我们将当前上下文(点)传递到每个模板。

示例

这组有限的牵强附会的示例演示了上面描述的一些概念。有关特定示例,请参阅 函数 、 方法 和 模板 文档。

条件块

请参阅 if 、 else 和 end 的文档。

{{ $var := 42 }}
{{ if eq $var 6 }}
  {{ print "var is 6" }}
{{ else if eq $var 7 }}
  {{ print "var is 7" }}
{{ else if eq $var 42 }}
  {{ print "var is 42" }}
{{ else }}
  {{ print "var is something else" }}
{{ end }}

逻辑运算符

请参阅 and 和 or 的文档。

{{ $v1 := true }}
{{ $v2 := false }}
{{ $v3 := false }}
{{ $result := false }}

{{ if and $v1 $v2 $v3 }}
  {{ $result = true }}
{{ end }}
{{ $result }} → false

{{ if or $v1 $v2 $v3 }}
  {{ $result = true }}
{{ end }}
{{ $result }} → true

循环

请参阅 range 、 else 和 end 的文档。

{{ $s := slice "foo" "bar" "baz" }}
{{ range $s }}
  <p>{{ . }}</p>
{{ else }}
  <p>The collection is empty</p>
{{ end }}

使用 seq 函数循环指定的次数:

{{ $total := 0 }}
{{ range seq 4 }}
  {{ $total = add $total . }}
{{ end }}
{{ $total }} → 10

重新绑定上下文

请参阅 with 、 else 和 end 的文档。

{{ $var := "foo" }}
{{ with $var }}
  {{ . }} → foo
{{ else }}
  {{ print "var is falsy" }}
{{ end }}

要测试多个条件:

{{ $v1 := 0 }}
{{ $v2 := 42 }}
{{ with $v1 }}
  {{ . }}
{{ else with $v2 }}
  {{ . }} → 42
{{ else }}
  {{ print "v1 and v2 are falsy" }}
{{ end }}

访问站点参数

请参阅 Site 对象上的 Params 方法的文档。

使用此站点配置:

hugo.
     
baseURL: https://example.org
params:
  author:
    email: [email protected]
    name: John Smith
  copyright-year: "2023"
  layouts:
    rfc_1123: Mon, 02 Jan 2006 15:04:05 MST
    rfc_3339: "2006-01-02T15:04:05-07:00"
  subtitle: The Best Widgets on Earth
title: ABC Widgets
baseURL = 'https://example.org'
title = 'ABC Widgets'
[params]
  copyright-year = '2023'
  subtitle = 'The Best Widgets on Earth'
  [params.author]
    email = '[email protected]'
    name = 'John Smith'
  [params.layouts]
    rfc_1123 = 'Mon, 02 Jan 2006 15:04:05 MST'
    rfc_3339 = '2006-01-02T15:04:05-07:00'
{
   "baseURL": "https://example.org",
   "params": {
      "author": {
         "email": "[email protected]",
         "name": "John Smith"
      },
      "copyright-year": "2023",
      "layouts": {
         "rfc_1123": "Mon, 02 Jan 2006 15:04:05 MST",
         "rfc_3339": "2006-01-02T15:04:05-07:00"
      },
      "subtitle": "The Best Widgets on Earth"
   },
   "title": "ABC Widgets"
}

通过链接标识符来访问自定义站点参数:

{{ .Site.Params.subtitle }} → The Best Widgets on Earth
{{ .Site.Params.author.name }} → John Smith

{{ $layout := .Site.Params.layouts.rfc_1123 }}
{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT

访问页面参数

请参阅 Page 对象上的 Params 方法的文档。

使用此前置内容:

content/news/annual-conference.md.
     
date: 2023-10-17T15:11:37-07:00
params:
  author:
    email: [email protected]
    name: John Smith
  display_related: true
title: Annual conference
date = 2023-10-17T15:11:37-07:00
title = 'Annual conference'
[params]
  display_related = true
  [params.author]
    email = '[email protected]'
    name = 'John Smith'
{
   "date": "2023-10-17T15:11:37-07:00",
   "params": {
      "author": {
         "email": "[email protected]",
         "name": "John Smith"
      },
      "display_related": true
   },
   "title": "Annual conference"
}

通过链接标识符来访问自定义页面参数:

{{ .Params.display_related }} → true
{{ .Params.author.name }} → John Smith

See also

  • EXIF
  • 代码块
  • 分页
  • Images
  • 块引用

On this page

  • 上下文
  • 操作
  • 变量
  • 函数
  • 方法
  • 注释
  • 包含
  • 示例
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 管道
  • 命令行界面
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护