Site 方法 on Hugo 中文文档

AllPages

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

（0.156.0 起弃用）

详见详情。

BaseURL

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

项目配置：

baseURL = 'https://example.org/docs/'

模板：

{{ .Site.BaseURL }} → https://example.org/docs/

BuildDrafts

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

（0.156.0 起弃用）

详见详情。

Config

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

Site 对象上的 Config 方法用于访问项目配置的一个子集，具体是 services 和 privacy 这两个键。

Services

参见配置 services。

例如，要使用 Hugo 内置的 Google Analytics 模板，你必须添加一个 Google tag ID：

[services.googleAnalytics]
id = 'G-XXXXXXXXX'

在模板中访问这个值：

{{ .Site.Config.Services.GoogleAnalytics.ID }} → G-XXXXXXXXX

如上面的示例所示，每个标识符都必须大写。

Copyright

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

项目配置：

copyright = '© 2023 ABC Widgets, Inc.'

模板：

{{ .Site.Copyright }} → © 2023 ABC Widgets, Inc.

Data

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

（0.156.0 起弃用）

请改用 hugo.Data 函数。

Dimension

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

（0.153.0 新增）

Site 对象上的 Dimension 方法返回给定维度的维度对象。

DIMENSION 参数必须是 language、version 或 role 之一。

示例	返回值	等价于
`{{ .Site.Dimension "language" }}`	`langs.Language`	`{{ .Site.Language }}`
`{{ .Site.Dimension "version" }}`	`version.Version`	`{{ .Site.Version }}`
`{{ .Site.Dimension "role" }}`	`roles.Role`	`{{ .Site.Role }}`

{{ $languageObject := .Site.Dimension "language" }}
{{ $languageObject.IsDefault }} → true
{{ $languageObject.Name }} → en

{{ $versionObject := .Site.Dimension "version" }}
{{ $versionObject.IsDefault }} → true
{{ $versionObject.Name }} → v1.0.0

{{ $roleObject := .Site.Dimension "role" }}
{{ $roleObject.IsDefault }} → true
{{ $roleObject.Name }} → guest

GetPage

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

GetPage 方法在 Page 对象上同样可用，此时可以指定相对于当前页面的路径。详见说明。

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

如果 Hugo 无法把路径解析为页面，该方法返回 nil。

Home

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

Site 对象上的 Home 方法是访问首页的便捷方式，其功能等价于：

{{ .Site.GetPage "/" }}

由于它返回 Page 对象，你可以通过链式调用使用任何可用的 page 方法。例如：

{{ .Site.Home.Store.Set "greeting" "Hello" }}

这个方法常用于生成指向首页的链接。例如：

项目配置：

baseURL = 'https://example.org/docs/'

模板：

{{ .Site.Home.Permalink }} → https://example.org/docs/
{{ .Site.Home.RelPermalink }} → /docs/

IsDefault

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

（0.156.0 新增）

Site 对象上的 IsDefault 方法报告给定站点在所有维度上是否为默认站点，这些维度包括语言、版本和角色。要确保某段代码在每次构建中只执行一次，无论你的维度生成了多少个站点，这个方法都很有用。

例如，下面的配置定义了一个横跨语言和版本两个维度的站点矩阵。

Language

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

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

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

方法

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

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

LanguagePrefix

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

考虑如下项目配置：

defaultContentLanguage = 'de'
defaultContentLanguageInSubdir = false

[languages.de]
direction = 'ltr'
label = 'Deutsch'
locale = 'de-DE'
title = 'Projekt Dokumentation'
weight = 1

[languages.en]
direction = 'ltr'
label = 'English'
locale = 'en-US'
title = 'Project Documentation'
weight = 2

访问德语站点时：

{{ .Site.LanguagePrefix }} → ""

访问英语站点时：

{{ .Site.LanguagePrefix }} → /en

如果把 defaultContentLanguageInSubdir 改为 true，那么访问德语站点时：

Languages

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

（0.156.0 起弃用）

详见详情。

Lastmod

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

Site 对象上的 Lastmod 方法返回一个 time.Time 值。请把它与时间函数和方法配合使用。例如：

{{ .Site.Lastmod | time.Format ":date_long" }} → January 31, 2024

MainSections

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

项目配置：

mainSections = ['books','films']

模板：

{{ .Site.MainSections }} → [books films]

如果项目配置中没有定义 mainSections，这个方法返回的切片只包含一个元素——即包含页面最多的顶层 section。

在如下内容结构中，films section 包含的页面最多：

Menus

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

Site 对象上的 Menus 方法返回菜单的集合，其中每个菜单包含一个或多个条目，条目可以是平铺的，也可以是嵌套的。每个条目指向站点内的某个页面，或指向外部资源。

Pages

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

这个方法按默认排序返回当前语言中所有页面 kind，其中包括首页、section 页面、分类法页面、术语页面和常规页面。

大多数情况下你应该改用 RegularPages 方法。

{{ range .Site.Pages }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

Param

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

Site 对象上的 Param 方法是一个便捷方法，用于返回项目配置中某个用户自定义参数的值。

[params]
display_toc = true

{{ .Site.Param "display_toc" }} → true

上面的写法等价于下面任意一种：

{{ .Site.Params.display_toc }}
{{ index .Site.Params "display_toc" }}

Params

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

项目配置如下：

[params]
  subtitle = 'The Best Widgets on Earth'
  copyright-year = '2023'
  [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'

通过链式调用标识符来访问自定义参数：

{{ .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

在上面这个模板示例中，每个键都是合法的标识符，例如没有哪个键包含连字符。要访问不是合法标识符的键，请使用 index 函数：

RegularPages

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

Site 对象上的 RegularPages 方法按默认排序返回所有常规页面的集合。

{{ range .Site.RegularPages }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

默认排序（default sort order）

default sort order

要改变排序方式，请使用 Pages 的任意一个排序方法。例如：

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

Role

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

（0.153.0 新增）

概述

Site 对象上的 Role 方法返回给定站点的 Role 对象，其内容来自项目配置中的角色定义。

方法

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

IsDefault

（bool）报告这是否为默认角色。

{{ .Site.Role.IsDefault }} → true

Name

（string）返回角色名称，即项目配置中转为小写的键名。

{{ .Site.Role.Name }} → guest

Sections

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

Site 对象上的 Sections 方法按默认排序返回顶层 section 页面的集合。

给定如下内容结构：

content/
├── books/
│   ├── book-1.md
│   └── book-2.md
├── films/
│   ├── film-1.md
│   └── film-2.md
└── _index.md

这个模板：

Sites

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

（0.156.0 起弃用）

请改用 hugo.Sites 函数。

Store

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

（0.139.0 新增）

用 Site 对象上的 Store 方法可以创建一个持久化的数据结构，用于存储和操作带 key 的值，作用域为当前站点。要创建其他作用域的数据结构，请参见下面的作用域一节。

Taxonomies

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

用法

从概念上说，Site 对象上的 Taxonomies 方法返回的数据结构形如：

taxonomy a:
  - term 1:
    - page 1
    - page 2
  - term 2:
    - page 1
taxonomy b:
  - term 1:
    - page 2
  - term 2:
    - page 1
    - page 2

例如，在一个书评站点上，你可能会创建两个分类法：一个用于体裁，另一个用于作者。

Title

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

项目配置：

title = 'My Documentation Site'

模板：

{{ .Site.Title }} → My Documentation Site

Version

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

（0.153.0 新增）

概述

Site 对象上的 Version 方法返回给定站点的 Version 对象，其内容来自项目配置中的版本定义。

方法

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

IsDefault

（bool）报告这是否为默认版本。

{{ .Site.Version.IsDefault }} → true

Name

（string）返回版本名称，即项目配置中转为小写的键名。

{{ .Site.Version.Name }} → v1.0.0