HUGO

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio 加星
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可证
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 入门
    • 本节内容
    • 快速开始
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 配置构建
    • 术语表
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • 前言
    • 构建选项
    • 页面资源
    • 图像处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基础模板
    • 主页模板
    • 单页模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 嵌入式模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • cast
    • collections
    • compare
    • crypto
    • css
    • data
    • debug
    • diagrams
    • encoding
    • fmt
    • global
    • go template
    • hash
    • hugo
    • images
    • inflect
    • js
    • lang
    • math
    • openapi3
    • os
    • partials
    • path
    • reflect
    • resources
    • safe
    • strings
    • templates
    • time
    • transform
    • urls
  • 方法
    • 本节内容
    • Duration
    • Menu
    • 菜单项
    • Page
    • Pager
    • Pages
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • 图像
    • 链接
    • 透传
    • 表格
  • 短代码
    • 本节内容
    • 注释
    • 详情
    • 图
    • Gist
    • 高亮
    • Instagram
    • Param
    • QR
    • Ref
    • Relref
    • Vimeo
    • X
    • YouTube
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo Pipes
    • 本节内容
    • 简介
    • 将 Sass 转译为 CSS
    • PostCSS
    • 后处理
    • JavaScript 构建
    • 资源压缩
    • 连接资源
    • 指纹和 SRI 哈希
    • 从字符串获取资源
    • 从模板获取资源
  • CLI
  • 故障排除
    • 本节内容
    • 审计
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • 常见问题
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • 搜索
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo Deploy
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Azure Static Web Apps 上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitHub Pages 上托管
    • 在 GitLab Pages 上托管
    • 在 KeyCDN 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
模板 基础

模板入门

创建模板以呈现您的内容、资源和数据。

模板是项目、主题或模块的 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 }}

在上面的示例中,当我们 range 遍历值切片时,上下文会发生变化。在第一次迭代中,上下文是“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 返回给定页面的 front matter 中定义的自定义参数的映射。
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 }} → Les Misérables

注释

请勿尝试使用 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: jsmith@example.org
    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 = 'jsmith@example.org'
    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": "jsmith@example.org",
         "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 方法的文档。

使用此 front matter

content/news/annual-conference.md.
     
date: 2023-10-17T15:11:37-07:00
params:
  author:
    email: jsmith@example.org
    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 = 'jsmith@example.org'
    name = 'John Smith'
{
   "date": "2023-10-17T15:11:37-07:00",
   "params": {
      "author": {
         "email": "jsmith@example.org",
         "name": "John Smith"
      },
      "display_related": true
   },
   "title": "Annual conference"
}

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

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

另请参阅

  • 块引用
  • 代码块
  • 颜色
  • Exif
  • 文件

在此页面上

  • 上下文
  • 操作
  • 变量
  • 函数
  • 方法
  • 评论
  • 包含
  • 示例
上次更新时间:2025 年 1 月 16 日: 将目录名称、文件名和文件路径格式化为代码 (8051ff818)
改进此页面
由 Hugo 作者提供
Hugo Logo
  • 提交问题
  • 获取帮助
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 

Hugo 赞助商

您的公司?
 

Hugo 徽标的版权归 Steve Francia 2013–2025 所有。

Hugo Gopher 基于 Renée French 的原创作品。

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 入门
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • 短代码
  • Hugo 模块
  • Hugo Pipes
  • CLI
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护