Hugo 文档

介绍

我们欢迎对文档的修正和改进。文档存在于与主项目分离的仓库中。要贡献：

• 对于现有文档的修正和改进，向 documentation repository 提交问题和拉取请求。
• 对于新功能的文档，在你对 project repository 的拉取请求中包含文档更改。

指南

风格

遵循 Google 的 developer documentation style guide。

Markdown

遵守以下 Markdown 约定：

• 使用 ATX 标题（级别 2-4），而不是 setext 标题。

• 使用 collapsed link references 而不是完整或快捷方式引用。例如：

  This is a [link][].
  
  [link]: https://example.org

• 使用 fenced code blocks 而不是 indented code blocks。

• 使用连字符而不是星号来表示无序 list items。

• 使用 callouts 而不是粗体文本进行强调。

• 不要在 Markdown 中混合使用 raw HTML。

• 不要使用粗体文本代替标题或描述术语 (dt)。

• 删除连续的空行。

• 删除尾随空格。

术语表

Glossary 术语在单个页面上定义，提供定义的中心仓库，尽管这些页面没有直接从网站链接。

定义必须是完整的句子，第一句定义术语。斜体化术语的第一次出现和任何引用的术语表术语以保持一致性。

使用此语法链接到术语表术语：[term](g)

术语查找不区分大小写，忽略格式，并支持单数和复数形式。例如，所有这些变体将链接到同一个术语表术语：

[global resource](g)
[Global Resource](g)
[Global Resources](g)
[`Global Resources`](g)

使用 glossary-term shortcode 插入术语定义：

{{% glossary-term "global resource" %}}

术语

根据需要链接到 glossary 并一致地使用术语。特别注意：

• “front matter”（两个单词，除非指配置键）
• “home page”（两个单词）
• “website”（一个单词）
• “standalone”（一个单词，无连字符）
• “map”（而不是"dictionary"）
• “flag”（而不是"option"用于命令行标志）
• “client side”（名词），“client-side”（形容词）
• “server side”（名词），“server-side”（形容词）
• “Markdown”（大写）
• “open-source”（连字符形容词）

模板类型

当你引用模板类型时，斜体化它：

When creating a _taxonomy_ template, do this...

但是，如果模板类型也是链接，不要斜体化它以避免分散注意力的格式：

When creating a [taxonomy] template, do this...

不要在标题、标题或 front matter 描述中斜体化模板类型。

标题和题头

• 使用句子风格的大写。
• 避免格式化字符串。
• 保持简洁。

页面描述

在编写页面 description 时，尽可能使用命令式现在时。例如：

---
description: Use these functions to read local or remote data files.
linkTitle: data
title: Data functions
---

+++
description = 'Use these functions to read local or remote data files.'
linkTitle = 'data'
title = 'Data functions'
+++

{
   "description": "Use these functions to read local or remote data files.",
   "linkTitle": "data",
   "title": "Data functions"
}

写作风格

尽可能使用主动语态和现在时。

不 → With Hugo you can build a static site.
是 → Build a static site with Hugo.

不 → This will cause Hugo to generate HTML files in the public directory.
是 → Hugo generates HTML files in the public directory.

使用第二人称而不是第三人称。

不 → Users should exercise caution when deleting files.
更好 → You must be cautious when deleting files.
最好 → Be cautious when deleting files.

最小化副词。

不 → Hugo is extremely fast.
是 → Hugo is fast.

函数和方法描述

以"Returns"开始函数和方法部分的描述，或者对于布尔值，使用"Reports whether"。

文件路径和名称

将目录名、文件名和文件路径包裹在反引号中，除非用于：

• 页面标题
• Section 标题 (h1-h6)
• 定义列表术语
• front matter 中的 description 字段

其他

其他最佳实践：

• 用句子或短语引入列表，而不是直接在标题下。
• 避免粗体文本；使用 callouts 进行强调。
• 不要将描述术语 (dt) 放在反引号中，除非语法上必要。
• 不要使用 Hugo 的 ref 或 relref shortcodes。
• 优先考虑当前的最佳实践，而不是多个选项或历史信息。
• 使用简短、专注的代码示例。
• 尽可能使用 basic english 以适应全球受众。

Front matter 字段

此站点使用下表列出的 front matter 字段。

在四个必需字段中，只有 title 和 description 需要数据。

title: The title
description: The description
categories: []
keywords: []

此示例演示了最低要求的 front matter 字段。

如果需要引号，尽可能优先使用单引号而不是双引号。

相关内容

可用时，“See also"侧边栏使用 Hugo 的 related content 功能显示相关页面，基于 front matter 关键字。我们通过在构建过程中针对 data/keywords.yaml 验证它们来确保关键字使用的一致性。如果找不到关键字，你将收到警报并且必须修改关键字或更新数据文件。此验证过程有助于完善相关内容以获得更好的结果。

如果"See also"侧边栏中的标题含糊不清或与另一个页面相同，你可以在 front matter 中定义备用标题：

linkTitle: Short title
params:
  alt_title: Whatever you want
title: Long descriptive title

linkTitle = 'Short title'
title = 'Long descriptive title'
[params]
  alt_title = 'Whatever you want'

{
   "linkTitle": "Short title",
   "params": {
      "alt_title": "Whatever you want"
   },
   "title": "Long descriptive title"
}

备用标题的使用仅限于"See also"侧边栏。

代码示例

使用模板代码示例：

• 使用两个空格缩进。
• 在开始动作分隔符后插入空格。
• 在结束动作分隔符前插入空格。
• 除非必要，不要向动作分隔符添加空白删除语法。例如，内联元素如 img 和 a 需要在两侧删除空白。

{{ if eq $foo $bar }}
  {{ fmt.Printf "%s is %s" $foo $bar }}
{{ end }}

围栏代码块

始终指定语言。

提供 Markdown 示例时，将代码语言设置为"text"以防止 shortcode 调用的错误词法分析/高亮。

```go-html-template
{{ if eq $foo "bar" }}
  {{ print "foo is bar" }}
{{ end }}
```

包含文件名标题和复制到剪贴板按钮：

```go-html-template {file="layouts/_partials/foo.html" copy=true}
{{ if eq $foo "bar" }}
  {{ print "foo is bar" }}
{{ end }}
```

使用非默认摘要在最初打开的 details 元素内包装代码块：

```go-html-template {details=true open=true summary="layouts/_partials/foo.html" copy=true}
{{ if eq $foo "bar" }}
  {{ print "foo is bar" }}
{{ end }}
```

默认启用空白修剪。要覆盖此行为并保留前导和尾随空格：

```go-html-template {trim=false}

{{ if eq $foo "bar" }}
  {{ print "foo is bar" }}
{{ end }}

```

Shortcode 调用

使用此语法：

```text
{{</* foo */>}}
{{%/* foo */%}}
```

站点配置

使用 code-toggle shortcode 包含站点配置示例：

{{< code-toggle file=hugo >}}
baseURL = 'https://example.org/'
languageCode = 'en-US'
title = 'My Site'
{{< /code-toggle >}}

Front matter

使用 code-toggle shortcode 包含 front matter 示例：

{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
title = 'My first post'
date = 2023-11-09T12:56:07-08:00
draft = false
{{< /code-toggle >}}

Callouts

要直观地强调重要信息，使用 callouts（admonitions）。Callout 类型不区分大小写。自 2025 年 3 月 8 日起，我们只使用五种可用类型中的三种。

• note（272 个实例）
• warning（2 个实例）
• caution（1 个实例）

限制 callout 类型的数量有助于我们一致地使用它们。

> [!note]
> Useful information that users should know, even when skimming content.

> [!warning]
> Urgent info that needs immediate user attention to avoid problems.

> [!caution]
> Advises about risks or negative outcomes of certain actions.

> [!tip]
> Helpful advice for doing things better or more easily.

> [!important]
> Key information users need to know to achieve their goal.

Shortcodes

这些 shortcodes 在整个文档中常用。其他 shortcodes 可用于专门用途。

code-toggle

使用 code-toggle shortcode 显示站点配置、front matter 或数据文件的示例。此 shortcode 采用以下参数：

config

(string) 要渲染的 site.Data.docs.config 部分。

copy

(bool) 是否显示复制到剪贴板按钮。默认为 false。

datakey:

(string) 要渲染的 site.Data.docs 部分。

file

(string) 在渲染的代码上方显示的文件名。对于站点配置示例，省略文件扩展名。

fm

(bool) 是否将代码渲染为 front matter。默认为 false。

skipHeader

(bool) 渲染 site.Data.docs.config 部分时是否省略顶级键。

{{< code-toggle file=hugo copy=true >}}
baseURL = 'https://example.org/'
languageCode = 'en-US'
title = 'My Site'
{{< /code-toggle >}}

deprecated-in

使用 deprecated-in shortcode 表示功能已弃用：

{{< deprecated-in 0.144.0 >}}

Use [`hugo.IsServer`] instead.

[`hugo.IsServer`]: /zh/functions/hugo/isserver/
{{< /deprecated-in >}}

eturl

使用嵌入式模板 URL (eturl) shortcode 插入指向嵌入式模板源代码的绝对 URL。此 shortcode 采用单个参数，模板的基本文件名（省略文件扩展名）。

This is a link to the [embedded alias template].

[embedded alias template]: <{{% eturl alias %}}>

glossary-term

使用 glossary-term shortcode 插入给定术语表术语的定义。

{{% glossary-term scalar %}}

include

使用 include shortcode 包含来自另一个页面的内容。

{{% include "_common/glob-patterns.md" %}}

new-in

使用 new-in shortcode 表示新功能：

{{< new-in 0.144.0 />}}

你还可以包含详细信息：

{{< new-in 0.144.0 >}}
This is a new feature.
{{< /new-in >}}

新功能

使用 new-in shortcode 表示新功能：

{{< new-in 0.144.0 >}}

如果指定版本早于预定义阈值，“new in"标签将被隐藏，基于主要和次要版本的差异。请参阅 details。

已弃用功能

使用 deprecated-in shortcode shortcode 表示功能已弃用：

{{< deprecated-in 0.144.0 >}}
Use [`hugo.IsServer`] instead.

[`hugo.IsServer`]: /zh/functions/hugo/isserver/
{{< /deprecated-in >}}

弃用函数或方法时，在 front matter 中添加如下内容：

---
expiryDate: '2027-02-17'
---

+++
expiryDate = '2027-02-17'
+++

{
   "expiryDate": "2027-02-17"
}

将 expiryDate 设置为从弃用日期起两年，并添加简短的 front matter 注释来解释设置。

GitHub 工作流

使用此工作流创建和提交拉取请求。

步骤 1

Fork documentation repository。

步骤 2

克隆你的 fork。

步骤 3

创建一个带有描述性名称的新分支，包括相应的问题编号（如果有）：

git checkout -b restructure-foo-page-99999

步骤 4

进行更改。

步骤 5

在本地构建站点以预览你的更改。

步骤 6

使用描述性的提交消息提交你的更改：

• 在第一行提供一个摘要，通常为 50 个字符或更少，后跟一个空行。
  • 以 content、theme、config、all 或 misc 之一开始摘要，后跟冒号、空格和以大写字母开头的更改的简要描述
  • 使用命令式现在时
• 可选择提供详细描述，每行 72 个字符或更少，后跟一个空行。
• 可选择添加一个或多个"Fixes"或"Closes"关键字，每个关键字单独一行，引用此更改解决的 issues。

例如：

git commit -m "content: Restructure the taxonomy page

This restructures the taxonomy page by splitting topics into logical
sections, each with one or more examples.

Fixes #9999
Closes #9998"

步骤 7

将新分支推送到文档仓库的 fork。

步骤 8

访问 documentation repository 并创建拉取请求 (PR)。

步骤 9

项目维护者将审查你的 PR 并可能请求更改。你可以在维护者合并你的 PR 后删除你的分支。