Page 方法 on Hugo 中文文档

Aliases

Fri, 02 Oct 2026 00:00:00 +0800

Page 对象上的 Aliases 方法返回 aliases 前置元数据字段中定义的值，形式为服务器相对 URL，并按当前内容维度解析。

Aliases 方法适合用来生成 _redirects 文件：其中为每个别名给出源 URL、目标 URL 与 HTTP 状态码。Cloudflare、GitLab Pages、Netlify 等托管服务都可以使用 _redirects 文件。

AllTranslations

Fri, 02 Oct 2026 00:00:00 +0800

使用如下项目配置：

defaultContentLanguage = 'en'

[languages.en]
contentDir = 'content/en'
label = 'English'
locale = 'en-US'
weight = 1

[languages.de]
contentDir = 'content/de'
label = 'Deutsch'
locale = 'de-DE'
weight = 2

[languages.fr]
contentDir = 'content/fr'
label = 'Français'
locale = 'fr-FR'
weight = 3

内容如下：

content/
├── de/
│   ├── books/
│   │   ├── book-1.md
│   │   └── book-2.md
│   └── _index.md
├── en/
│   ├── books/
│   │   ├── book-1.md
│   │   └── book-2.md
│   └── _index.md
├── fr/
│   ├── books/
│   │   └── book-1.md
│   └── _index.md
└── _index.md

模板如下：

AlternativeOutputFormats

Fri, 02 Oct 2026 00:00:00 +0800

输出格式（output format）

Page 对象上的 AlternativeOutputFormats 方法返回一个 OutputFormat 对象切片，其中不包含当前输出格式，每一项代表给定页面启用的一个输出格式。详见说明。

例如，为每个备选输出格式各生成一个 link 元素：

Ancestors

Fri, 02 Oct 2026 00:00:00 +0800

内容结构如下：

content/
├── auctions/
│   ├── 2023-11/
│   │   ├── _index.md     <-- front matter: weight = 202311
│   │   ├── auction-1.md
│   │   └── auction-2.md
│   ├── 2023-12/
│   │   ├── _index.md     <-- front matter: weight = 202312
│   │   ├── auction-3.md
│   │   └── auction-4.md
│   ├── _index.md         <-- front matter: weight = 30
│   ├── bidding.md
│   └── payment.md
├── books/
│   ├── _index.md         <-- front matter: weight = 10
│   ├── book-1.md
│   └── book-2.md
├── films/
│   ├── _index.md         <-- front matter: weight = 20
│   ├── film-1.md
│   └── film-2.md
└── _index.md

模板如下：

BundleType

Fri, 02 Oct 2026 00:00:00 +0800

页面包（page bundle）是把内容与关联资源封装在一起的目录。页面包有两种类型：叶子包与分支包。详见说明。

Page 对象上的 BundleType 方法对分支包返回 branch，对叶子包返回 leaf，若该页面不是页面包则返回空字符串。

CodeOwners

Fri, 02 Oct 2026 00:00:00 +0800

GitHub 与 GitLab 都支持 CODEOWNERS 文件。该文件指定负责开发和维护软件与文档的用户，其声明可以作用于整个仓库、特定目录，也可以作用于单个文件。了解更多：

使用 Page 对象上的 CodeOwners 方法可以确定给定页面的代码所有者。

Content

Fri, 02 Oct 2026 00:00:00 +0800

Page 对象上的 Content 方法把 Markdown 与短代码（shortcode）渲染为 HTML。

{{ .Content }}

ContentWithoutSummary

Fri, 02 Oct 2026 00:00:00 +0800

在使用手动或自动内容摘要时，Page 对象上的 ContentWithoutSummary 方法会把 Markdown 与短代码渲染为 HTML，并在结果中剔除内容摘要。

如果你在前置元数据中定义内容摘要，ContentWithoutSummary 方法的返回值与 Content 相同。

CurrentSection

Fri, 02 Oct 2026 00:00:00 +0800

section（内容区块）

内容结构如下：

content/
├── auctions/
│   ├── 2023-11/
│   │   ├── _index.md     <-- current section: 2023-11
│   │   ├── auction-1.md
│   │   └── auction-2.md  <-- current section: 2023-11
│   ├── 2023-12/
│   │   ├── _index.md
│   │   ├── auction-3.md
│   │   └── auction-4.md
│   ├── _index.md         <-- current section: auctions
│   ├── bidding.md
│   └── payment.md        <-- current section: auctions
├── books/
│   ├── _index.md         <-- current section: books
│   ├── book-1.md
│   └── book-2.md         <-- current section: books
├── films/
│   ├── _index.md         <-- current section: films
│   ├── film-1.md
│   └── film-2.md         <-- current section: films
└── _index.md             <-- current section: home

要创建指向当前 section 页面的链接：

Data

Fri, 02 Oct 2026 00:00:00 +0800

Page 对象上的 Data 方法为每种页面种类返回各自特有的数据对象。

Date

Fri, 02 Oct 2026 00:00:00 +0800

在前置元数据中设置日期：

title = 'Article 1'
date = 2023-10-19T00:40:04-07:00

日期是 time.Time 值。可以用 time.Format 函数格式化并本地化该值，也可以把它用于任何时间方法。

Description

Fri, 02 Oct 2026 00:00:00 +0800

页面描述在概念上不同于内容摘要，通常用于页面自身的元数据。

title = 'How to make spicy tuna hand rolls'
description = 'Instructions for making spicy tuna hand rolls.'

layouts/baseof.html

<head>
  <meta name="description" content="{{ .Description }}">
</head>

Draft

Fri, 02 Oct 2026 00:00:00 +0800

默认情况下，构建项目时 Hugo 不会发布草稿页面。要在构建项目时包含草稿页面，请使用 --buildDrafts 命令行标志。

title = 'Post 1'
draft = true

{{ .Draft }} → true

Eq

Fri, 02 Oct 2026 00:00:00 +0800

在这个刻意构造的例子中，我们列出当前 section 中除当前页面之外的所有页面。

layouts/page.html

{{ $currentPage := . }}
{{ range .CurrentSection.Pages }}
  {{ if not (.Eq $currentPage) }}
    <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
  {{ end }}
{{ end }}

ExpiryDate

Fri, 02 Oct 2026 00:00:00 +0800

默认情况下，构建项目时 Hugo 会排除已过期的页面。要包含已过期的页面，请使用 --buildExpired 命令行标志。

在前置元数据中设置过期日期：

title = 'Article 1'
expiryDate = 2024-10-19T00:32:13-07:00

过期日期是 time.Time 值。可以用 time.Format 函数格式化并本地化该值，也可以把它用于任何时间方法。

File

Fri, 02 Oct 2026 00:00:00 +0800

默认情况下，并非所有页面都有对应的文件，包括顶层 section 页、分类法页与术语页。顾名思义，文件不存在时你无法取得文件信息。

要让上述某类页面拥有对应文件，请在相应目录中创建 _index.md 文件。例如：

content/
└── books/
    ├── _index.md  <-- the top-slevel section page
    ├── book-1.md
    └── book-2.md

FirstSection

Fri, 02 Oct 2026 00:00:00 +0800

section（内容区块）

内容结构如下：

content/
├── auctions/
│   ├── 2023-11/
│   │   ├── _index.md     <-- first section: auctions
│   │   ├── auction-1.md
│   │   └── auction-2.md  <-- first section: auctions
│   ├── 2023-12/
│   │   ├── _index.md
│   │   ├── auction-3.md
│   │   └── auction-4.md
│   ├── _index.md         <-- first section: auctions
│   ├── bidding.md
│   └── payment.md        <-- first section: auctions
├── books/
│   ├── _index.md         <-- first section: books
│   ├── book-1.md
│   └── book-2.md         <-- first section: books
├── films/
│   ├── _index.md         <-- first section: films
│   ├── film-1.md
│   └── film-2.md         <-- first section: films
└── _index.md             <-- first section: home

要链接到当前页面所属的顶层 section：

Fragments

Fri, 02 Oct 2026 00:00:00 +0800

在 URL 中，无论绝对路径还是相对路径，片段都指向页面上某个 HTML 元素的 id 属性。

/articles/article-1#section-2
------------------- ---------
       path         fragment

Hugo 会为页面内容中的每个 Markdown ATX 与 setext 标题分配 id 属性。你可以按需用 Markdown 属性覆盖该 id。这就在目录（TOC）条目与页面上的标题之间建立了对应关系。

使用 Page 对象上的 Fragments 方法，可以用 Fragments.ToHTML 方法生成目录，也可以遍历 Fragments.Map 数据结构。用下面的方法来检查、校验并渲染页面片段。

FuzzyWordCount

Fri, 02 Oct 2026 00:00:00 +0800

{{ .FuzzyWordCount }} → 200

要得到精确的单词数，请使用 WordCount 方法。

GetPage

Fri, 02 Oct 2026 00:00:00 +0800

GetPage 方法在 Site 对象上也可用。详见说明。

在 Page 对象上使用 GetPage 方法时，请指定相对于当前目录或相对于 content 目录的路径。

如果 Hugo 无法把路径解析为页面，该方法返回 nil。如果路径有歧义，Hugo 会抛出错误并中止构建。

GetTerms

Fri, 02 Oct 2026 00:00:00 +0800

给定如下前置元数据：

title = 'Les Misérables'
tags = ['historical','classic','fiction']

这段模板代码：

{{ with .GetTerms "tags" }}
  <p>Tags</p>
  <ul>
    {{ range . }}
      <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
    {{ end }}
  </ul>
{{ end }}

会渲染为：

<p>Tags</p>
<ul>
  <li><a href="/tags/historical/">historical</a></li>
  <li><a href="/tags/classic/">classic</a></li>
  <li><a href="/tags/fiction/">fiction</a></li>
</ul>

GitInfo

Fri, 02 Oct 2026 00:00:00 +0800

Page 对象上的 GitInfo 方法可以访问 Git 历史中的提交元数据，例如作者姓名、提交哈希与提交信息。

前置条件

安装 Git，创建仓库，并提交项目文件。

HasMenuCurrent

Fri, 02 Oct 2026 00:00:00 +0800

如果菜单项关联的 Page 对象是一个 section，那么对该 section 的任何后代页面，这个方法同样返回 true。

{{ $currentPage := . }}
{{ range site.Menus.main }}
  {{ if $currentPage.IsMenuCurrent .Menu . }}
    <a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a>
  {{ else if $currentPage.HasMenuCurrent .Menu . }}
    <a class="ancestor" aria-current="true" href="{{ .URL }}">{{ .Name }}</a>
  {{ else }}
    <a href="{{ .URL }}">{{ .Name }}</a>
  {{ end }}
{{ end }}

完整示例见菜单模板。

HasShortcode

Fri, 02 Oct 2026 00:00:00 +0800

举个例子，我们用 Plotly 渲染一张图表：

content/example.md

{{< plotly >}}
{
  "data": [
    {
      "x": ["giraffes", "orangutans", "monkeys"],
      "y": [20, 14, 23],
      "type": "bar"
    }
  ],
}
{{< /plotly >}}

这个短代码很简单：

layouts/_shortcodes/plotly.html

{{ $id := printf "plotly-%02d" .Ordinal }}
<div id="{{ $id }}"></div>
<script>
  Plotly.newPlot(document.getElementById({{ $id }}), {{ .Inner | safeJS }});
</script>

现在我们可以只在调用 plotly 短代码的页面上按需加载所需的 JavaScript：

HeadingsFiltered

Fri, 02 Oct 2026 00:00:00 +0800

与 Pages 对象上的 Related 方法配合使用。详见说明。

InSection

Fri, 02 Oct 2026 00:00:00 +0800

section（内容区块）

Page 对象上的 InSection 方法报告给定页面是否位于给定 section 中。注意，把页面与其同级页面作比较时，该方法返回 true。

基本用法

内容结构如下：

content/
├── auctions/
│   ├── 2023-11/
│   │   ├── _index.md
│   │   ├── auction-1.md
│   │   └── auction-2.md
│   ├── 2023-12/
│   │   ├── _index.md
│   │   ├── auction-3.md
│   │   └── auction-4.md
│   ├── _index.md
│   ├── bidding.md
│   └── payment.md
└── _index.md

渲染 auction-1 页面时：

IsAncestor

Fri, 02 Oct 2026 00:00:00 +0800

基本用法

内容结构如下：

content/
├── auctions/
│   ├── 2023-11/
│   │   ├── _index.md
│   │   ├── auction-1.md
│   │   └── auction-2.md
│   ├── 2023-12/
│   │   ├── _index.md
│   │   ├── auction-3.md
│   │   └── auction-4.md
│   ├── _index.md
│   ├── bidding.md
│   └── payment.md
└── _index.md

渲染 auctions 页面时：

IsBranch

Fri, 02 Oct 2026 00:00:00 +0800

（0.163.0 新增）

分支

content/
├── books/
│   ├── book-1/
│   │   └── index.md    <-- kind = page      IsBranch = false
│   ├── book-2.md       <-- kind = page      IsBranch = false
│   └── _index.md       <-- kind = section   IsBranch = true
├── tags
│   ├── fiction
│   │   └── _index.md   <-- kind = term      IsBranch = true
│   └── _index.md       <-- kind = taxonomy  IsBranch = true
└── _index.md           <-- kind = home      IsBranch = true

{{ .IsBranch }}

IsDescendant

Fri, 02 Oct 2026 00:00:00 +0800

基本用法

内容结构如下：

content/
├── auctions/
│   ├── 2023-11/
│   │   ├── _index.md
│   │   ├── auction-1.md
│   │   └── auction-2.md
│   ├── 2023-12/
│   │   ├── _index.md
│   │   ├── auction-3.md
│   │   └── auction-4.md
│   ├── _index.md
│   ├── bidding.md
│   └── payment.md
└── _index.md

渲染 auctions 页面时：

IsHome

Fri, 02 Oct 2026 00:00:00 +0800

如果页面种类为 home，Page 对象上的 IsHome 方法就返回 true。

content/
├── books/
│   ├── book-1/
│   │   └── index.md  <-- kind = page
│   ├── book-2.md     <-- kind = page
│   └── _index.md     <-- kind = section
└── _index.md         <-- kind = home

{{ .IsHome }}

IsMenuCurrent

Fri, 02 Oct 2026 00:00:00 +0800

{{ $currentPage := . }}
{{ range site.Menus.main }}
  {{ if $currentPage.IsMenuCurrent .Menu . }}
    <a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a>
  {{ else if $currentPage.HasMenuCurrent .Menu . }}
    <a class="ancestor" aria-current="true" href="{{ .URL }}">{{ .Name }}</a>
  {{ else }}
    <a href="{{ .URL }}">{{ .Name }}</a>
  {{ end }}
{{ end }}

完整示例见菜单模板。

IsNode

Fri, 02 Oct 2026 00:00:00 +0800

（0.163.0 起弃用） 请改用 IsBranch 方法。

IsPage

Fri, 02 Oct 2026 00:00:00 +0800

如果页面种类为 page，Page 对象上的 IsPage 方法就返回 true。

content/
├── books/
│   ├── book-1/
│   │   └── index.md  <-- kind = page
│   ├── book-2.md     <-- kind = page
│   └── _index.md     <-- kind = section
└── _index.md         <-- kind = home

{{ .IsPage }}

IsSection

Fri, 02 Oct 2026 00:00:00 +0800

如果页面种类为 section，Page 对象上的 IsSection 方法就返回 true。

content/
├── books/
│   ├── book-1/
│   │   └── index.md  <-- kind = page
│   ├── book-2.md     <-- kind = page
│   └── _index.md     <-- kind = section
└── _index.md         <-- kind = home

{{ .IsSection }}

IsTranslated

Fri, 02 Oct 2026 00:00:00 +0800

使用如下项目配置：

defaultContentLanguage = 'en'

[languages.en]
contentDir = 'content/en'
label = 'English'
locale = 'en-US'
weight = 1

[languages.de]
contentDir = 'content/de'
label = 'Deutsch'
locale = 'de-DE'
weight = 2

内容如下：

content/
├── de/
│   ├── books/
│   │   └── book-1.md
│   └── _index.md
├── en/
│   ├── books/
│   │   ├── book-1.md
│   │   └── book-2.md
│   └── _index.md
└── _index.md

渲染 content/en/books/book-1.md 时：

Keywords

Fri, 02 Oct 2026 00:00:00 +0800

默认情况下，Hugo 在创建相关内容集合时会用到关键词。

title = 'How to make spicy tuna hand rolls'
keywords = ['tuna','sriracha','nori','rice']

在模板中列出关键词：

{{ range .Keywords }}
  {{ . }}
{{ end }}

或者使用 delimit 函数：

{{ delimit .Keywords ", " ", and " }} → tuna, sriracha, nori, and rice

关键词也可以用作一种有用的分类法：

[taxonomies]
tag = 'tags'
keyword = 'keywords'
category = 'categories'

Kind

Fri, 02 Oct 2026 00:00:00 +0800

页面种类是 home、page、section、taxonomy 或 term 之一。

content/
├── books/
│   ├── book-1/
│   │   └── index.md    <-- kind = page
│   ├── book-2.md       <-- kind = page
│   └── _index.md       <-- kind = section
├── tags/
│   ├── fiction/
│   │   └── _index.md   <-- kind = term
│   └── _index.md       <-- kind = taxonomy
└── _index.md           <-- kind = home

在模板中取值：

Language

Fri, 02 Oct 2026 00:00:00 +0800

Page 对象上的 Language 方法返回给定页面的 Language 对象，其内容来自项目配置中的语言定义。

你也可以在 Site 对象上使用 Language 方法。详见说明。

方法

在 Language 对象上使用这些方法。

下面的示例都基于如下语言定义。

Lastmod

Fri, 02 Oct 2026 00:00:00 +0800

在前置元数据中设置最后修改日期：

title = 'Article 1'
lastmod = 2023-10-19T00:40:04-07:00

最后修改日期是 time.Time 值。可以用 time.Format 函数格式化并本地化该值，也可以把它用于任何时间方法。

{{ .Lastmod | time.Format ":date_medium" }} → Oct 19, 2023

上面的例子中，我们在前置元数据里显式设置了最后修改日期。在 Hugo 的默认配置下，Lastmod 方法返回前置元数据中的值。这一行为是可配置的，你可以：

Layout

Fri, 02 Oct 2026 00:00:00 +0800

在前置元数据中指定 layout 字段即可指向特定模板。详见说明。

title = 'Contact'
layout = 'contact'

Hugo 会用 contact.html 渲染该页面。

layouts/
├── baseof.html
├── contact.html
├── home.html
├── page.html
├── section.html
├── taxonomy.html
└── term.html

虽然在模板中很少用到，但你可以这样取值：

Len

Fri, 02 Oct 2026 00:00:00 +0800

{{ .Len }} → 42

LinkTitle

Fri, 02 Oct 2026 00:00:00 +0800

LinkTitle 方法返回前置元数据中定义的 linkTitle 字段；若未定义，则回退到 Title 方法的返回值。

title = 'Seventeen delightful recipes for healthy desserts'
linkTitle = 'Dessert recipes'

{{ .LinkTitle }} → Dessert recipes

如上所示，当页面标题很长时，在前置元数据中定义链接标题是有好处的。在模板中生成锚元素时可以用它：

Fri, 02 Oct 2026 00:00:00 +0800

Hugo 按以下排序层级对站点的常规页面集合排序，据此确定_下一个_和_上一个_页面：

字段	优先级	排序方向
`weight`	1	降序
`date`	2	降序
`linkTitle`	3	降序
`path`	4	降序

用于确定_下一个_和_上一个_页面的这个已排序页面集合独立于其他页面集合，因此可能导致意外的行为。

NextInSection

Fri, 02 Oct 2026 00:00:00 +0800

Hugo 按以下排序层级对当前 section 的常规页面排序，据此确定_下一个_和_上一个_页面：

字段	优先级	排序方向
`weight`	1	降序
`date`	2	降序
`linkTitle`	3	降序
`path`	4	降序

用于确定_下一个_和_上一个_页面的这个已排序页面集合独立于其他页面集合，因此可能导致意外的行为。

OutputFormats

Fri, 02 Oct 2026 00:00:00 +0800

输出格式（output format）

Page 对象上的 OutputFormats 方法返回一组 OutputFormat 对象，每个对象对应该页面已启用的一种输出格式。详见[说明][]。

方法

在 OutputFormats 对象上使用这些方法。

Canonical

（0.154.4 新增）

（page.OutputFormat）返回当前页面的规范输出格式（如果已定义）。获取该对象后，可以使用它的任意[关联方法][]。

{{ with .Site.Home.OutputFormats.Canonical }}
  {{ .MediaType.Type }} → text/html
  {{ .MediaType.MainType }} → text
  {{ .MediaType.SubType }} → html
  {{ .Name }} → html
  {{ .Permalink }} → https://example.org/
  {{ .Rel }} → canonical
  {{ .RelPermalink }} → /
{{ end }}

Get

（page.OutputFormat）返回具有给定标识符的 OutputFormat 对象。获取该对象后，可以使用它的任意[关联方法][]。

{{ with .Site.Home.OutputFormats.Get "rss" }}
  {{ .MediaType.Type }} → application/rss+xml
  {{ .MediaType.MainType }} → application
  {{ .MediaType.SubType }} → rss
  {{ .Name }} → rss
  {{ .Permalink }} → https://example.org/index.xml
  {{ .Rel }} → alternate
  {{ .RelPermalink }} → /index.xml
{{ end }}

示例

要渲染指向当前页面规范输出格式的 link 元素：

Page

Fri, 02 Oct 2026 00:00:00 +0800

这是一个便捷方法，当_局部模板_同时被_短代码_和其他模板类型调用时很有用。

layouts/_shortcodes/foo.html

{{ partial "my-partial.html" . }}

当_短代码_模板调用该_局部模板_时，会把当前上下文（即点号）传递过去。该上下文包含 Page、Params、Inner、Name 等标识符。

Pages

Fri, 02 Oct 2026 00:00:00 +0800

Page 对象上的 Pages 方法可用于这些页面类型：home、section、taxonomy 和 term。这些页面类型的模板会在上下文中接收一个页面集合，并按默认排序顺序排列。

在模板中遍历该页面集合：

{{ range .Pages.ByTitle }}
  <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}

考虑如下内容结构：

content/
├── lessons/
│   ├── lesson-1/
│   │   ├── _index.md
│   │   ├── part-1.md
│   │   └── part-2.md
│   ├── lesson-2/
│   │   ├── resources/
│   │   │   ├── task-list.md
│   │   │   └── worksheet.md
│   │   ├── _index.md
│   │   ├── part-1.md
│   │   └── part-2.md
│   ├── _index.md
│   ├── grading-policy.md
│   └── lesson-plan.md
├── _index.md
├── contact.md
└── legal.md

渲染首页时，Pages 方法返回：

Paginate

Fri, 02 Oct 2026 00:00:00 +0800

分页（pagination）是指把一个列表页面拆分成两个或多个分页器（pager），每个分页器包含页面集合的一个子集，以及指向其他分页器的导航链接。

Paginator

Fri, 02 Oct 2026 00:00:00 +0800

分页（pagination）是指把一个列表页面拆分成两个或多个分页器（pager），每个分页器包含页面集合的一个子集，以及指向其他分页器的导航链接。

Param

Fri, 02 Oct 2026 00:00:00 +0800

Page 对象上的 Param 方法会在页面参数中查找给定的 KEY，并返回对应的值。如果在页面参数中找不到该 KEY，它会到站点参数中查找。如果两处都找不到，Param 方法返回 nil。