文档

简介

我们欢迎对文档进行更正和改进。请注意，文档位于其自身的存储库中，与项目存储库分开。

对于当前文档的更正和改进，请向 文档存储库 提交问题和拉取请求。

对于与新功能相关的文档，请在向 项目存储库 提交拉取请求时包含文档更改。

指南

Markdown

请遵循以下指南：

• 使用 ATX 标题，而不是 setext 标题，级别为2到4
• 使用 围栏代码块 ，而不是 缩进代码块
• 使用连字符，而不是星号，以及无序 列表项
• 使用 note 短代码 ，而不是块引用
• 不要在 Markdown 中混合使用 原始 HTML
• 不要使用粗体文本代替标题或描述术语（ dt ）
• 删除连续的空行（最多两行）
• 删除尾随空格

样式

请遵守 Google 的 开发者文档样式指南 。

术语

如有必要，请链接到 术语表 ，并在整个文档中始终如一地使用这些术语。特别需要注意的是：

• 除非您指的是配置键，“前置内容”一词应为两个单词
• “主页”一词应为两个单词
• “网站”一词应为一个单词
• “独立式”一词应为一个单词，不用连字符
• 使用“map”（映射）代替“dictionary”（字典）
• 当指代命令行标志时，使用“flag”（标志）代替“option”（选项）
• 将“Markdown”首字母大写
• 将“open-source”（开源）用作形容词时使用连字符。

页面标题和标题

请遵循页面标题和标题的以下指南：

• 使用句子式大写
• 避免在标题和页面标题中使用格式化字符串
• 越短越好

使用主动语态和现在时

在软件文档中，被动语态在某些情况下是不可避免的。请尽可能使用主动语态。

否 → 使用 Hugo，您可以构建静态网站。 是 → 使用 Hugo 构建静态网站。

否 → 这将导致 Hugo 在 public 目录中生成 HTML 文件。 是 → Hugo 在 public 目录中生成 HTML 文件。

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

否 → 用户在删除文件时应谨慎。 较好 → 删除文件时必须谨慎。 最好 → 删除文件时请谨慎。

尽可能避免使用副词

否 → Hugo 非常快。 是 → Hugo 很快。

6 级标题

6 级标题的样式为 dt 元素。这是为了支持带有可链接术语的 词汇表 而实现的。

函数和方法描述

向 函数 或 方法 部分添加页面时，请以“返回”一词开头描述。对于返回布尔值的函数和方法，请以短语“报告是否”开头描述。

例如：

• 返回在前置内容中定义的 URL 别名。
• 报告给定页面是否在给定部分中。

其他

其他需要考虑的指南：

• 不要将列表项直接放在标题下；在列表之前包含一个介绍性句子或短语。
• 避免使用 粗体 文本。使用 note 短代码 来引起对重要内容的注意。
• 除非语法清晰度需要，否则不要将描述术语（ dt ）放在反引号中。
• 不要使用 Hugo 的 ref 或 relref 短代码。我们使用链接渲染钩子来解析和验证链接目标，包括片段。
• 越短越好。如果有多种方法可以执行某项操作，请描述当前的最佳实践。例如，避免使用诸如“您也可以…”和“在旧版本中，您必须…”之类的短语。
• 包含代码示例时，请使用演示该概念的简短片段。
• Hugo 用户社区是全球性的；尽可能使用 基础英语 。

代码示例

代码缩进两个空格。对于模板代码示例，在打开操作分隔符后包含一个空格，并在关闭操作分隔符前包含一个空格。

围栏代码块

使用围栏代码块时，始终包含语言代码：

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

渲染结果：

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

短代码调用

使用此语法在代码示例中包含短代码调用：

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

渲染结果：

{{< foo >}}
{{% foo %}}

站点配置

使用 code-toggle 短代码 包含站点配置示例：

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

渲染结果：

baseURL: https://example.org/
languageCode: en-US
title: My Site

baseURL = 'https://example.org/'
languageCode = 'en-US'
title = 'My Site'

{
   "baseURL": "https://example.org/",
   "languageCode": "en-US",
   "title": "My Site"
}

前置内容

使用 code-toggle 短代码 包含前置内容示例：

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

渲染结果：

---
date: 2023-11-09T12:56:07-08:00
draft: false
title: My first post
---

+++
date = 2023-11-09T12:56:07-08:00
draft = false
title = 'My first post'
+++

{
   "date": "2023-11-09T12:56:07-08:00",
   "draft": false,
   "title": "My first post"
}

其他代码示例

对于需要文件名 的其他代码示例，请使用 code 短代码 ：

{{< code file=layouts/_default/single.html >}}
{{ range .Site.RegularPages }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{< /code >}}

渲染结果：

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

短代码

这些短代码在整个文档中经常使用。其他短代码可用于特殊用途。

code

对于需要文件名的其他代码示例，请使用“code”短代码。请参见上面的 代码示例 。此短代码采用以下参数：

copy

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

file

(string) 要显示的文件名。

lang

(string) 代码语言。如果您不提供 lang 参数，则代码语言由文件扩展名确定。如果文件扩展名为 html ，则将代码语言设置为 go-html-template 。默认为 text 。

code-toggle

使用“code-toggle”短代码显示站点配置、前置内容或数据文件的示例。请参见上面的 代码示例 。此短代码采用以下参数：

copy

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

file

(string) 要显示的文件名。对于站点配置示例，请省略文件扩展名。

fm

(bool) 示例是否是前置内容。默认为 false 。

deprecated-in

使用“deprecated-in”短代码指示功能已弃用：

{{% deprecated-in 0.127.0 %}}
改用 [`hugo.IsServer`](/functions/hugo/isserver/) 。

[`hugo.IsServer`]: /functions/hugo/isserver/
{{% /deprecated-in %}}

渲染结果：

eturl

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

这是指向 [嵌入式别名模板](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html) 的链接。

[嵌入式别名模板]: {{% eturl alias %}}

渲染结果：

这是指向 嵌入式别名模板 的链接。

new-in

使用“new-in”短代码指示新功能：

{{< new-in 0.127.0 >}}

渲染结果：

note

使用带 {{% %}} 分隔符的“note”短代码来引起对重要内容的注意：

{{% note %}}
使用 [`math.Mod`](/functions/math/mod/) 函数来控制……

[`math.Mod`]: /functions/math/mod/
{{% /note %}}

渲染结果：

新功能

使用“new-in”短代码指示新功能：

{{< new-in 0.120.0 >}}

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

已弃用的功能

使用“deprecated-in”短代码指示功能已弃用：

{{% deprecated-in 0.120.0 %}}
改用 [`hugo.IsServer`](/functions/hugo/isserver/) 。

[`hugo.IsServer`]: /functions/hugo/isserver/
{{% /deprecated-in %}}

弃用函数或方法时，请将其添加到前置内容：

---
expiryDate: "2024-10-30"
---

+++
expiryDate = '2024-10-30'
+++

{
   "expiryDate": "2024-10-30"
}

将 expiryDate 设置为弃用日期后的一年，并添加简短的前置内容注释以解释此设置。

GitHub 工作流程

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

步骤 1

分叉 文档存储库 。

步骤 2

克隆您的分叉。

步骤 3

使用描述性名称创建一个新分支，如果适用，则包含相应的编号：

git checkout -b restructure-foo-page-99999

步骤 4

进行更改。

步骤 5

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

步骤 6

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

• 在第一行提供摘要，通常少于 50 个字符，后跟一个空行。
• 可选，提供详细说明，其中每一行少于 80 个字符，后跟一个空行。
• 可选，添加一个或多个“Fixes”或“Closes”关键字，每一行一个，引用此更改解决的 问题 。

例如：

git commit -m "重构分类页面

此更改通过将主题拆分为逻辑部分来重构分类页面，每个部分包含一个或多个示例。

修复 #9999
关闭 #9998"

步骤 7

将新分支推送到您在文档存储库中的分叉。

步骤 8

访问 文档存储库 并创建一个拉取请求 (PR)。

步骤 9

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