文档
简介
我们欢迎对文档的更正和改进。请注意，文档位于其自己的存储库中，与项目存储库分开。
要更正和改进当前文档，请将问题和拉取请求提交到文档存储库。
对于与新功能相关的文档，请在将拉取请求提交到项目存储库时，包含文档更改。
准则
Markdown
请遵循以下准则
- 使用ATX标题，而不是Setext标题，级别为2到4
- 使用围栏代码块，而不是缩进代码块
- 在无序列表项中使用连字符，而不是星号
- 使用note 短代码而不是块引用
- 不要在 Markdown 中混合使用原始 HTML
- 不要使用粗体文本代替标题或描述术语 (
dt) - 删除连续的空行（最多两行）
- 删除尾随空格
样式
请遵守 Google 的开发者文档风格指南。
术语
请在必要时链接到术语表，并在整个文档中一致地使用这些术语。特别注意
- “前置信息”一词是两个词，除非您指的是配置键
- “主页”一词是两个词
- “网站”一词是一个词
- “standalone”一词是一个词，而不是用连字符连接
- 使用“map”一词代替“dictionary”
- 在引用命令行标志时，使用“flag”一词代替“option”
- 将“Markdown”一词大写
- 当用作形容词时，用连字符连接“open-source”一词。
页面标题和标题
请遵循以下关于页面标题和标题的准则
- 使用句子式大小写
- 避免在标题和页面标题中使用格式化的字符串
- 越短越好
使用主动语态和现在时
在软件文档中，在某些情况下被动语态是不可避免的。请尽可能使用主动语态。
否 → 使用 Hugo，您可以构建一个静态站点。
是 → 使用 Hugo 构建一个静态站点。
否 → 这将导致 Hugo 在 public 目录中生成 HTML 文件。
是 → Hugo 在 public 目录中生成 HTML 文件。
使用第二人称而非第三人称
反例 → 用户在删除文件时应谨慎。
较好 → 您在删除文件时必须谨慎。
最佳 → 删除文件时请谨慎。
尽可能避免使用副词
反例 → Hugo 非常快。
正例 → Hugo 很快。
6 级标题
6 级标题的样式为 dt 元素。此实现是为了支持带有可链接术语的词汇表。
函数和方法描述
当向 函数 或 方法 部分添加页面时，请以“返回”一词开始描述。对于返回布尔值的函数和方法，请以短语“报告是否”开始描述。
例如
返回在前端定义的 URL 别名。报告给定的页面是否在给定的部分中。
目录名称、文件名和文件路径
将目录名称、文件名和文件路径用反引号括起来，以下情况除外
- 页面标题
- 章节标题 (h1-h6)
- 定义列表术语
- 前端中的描述字段
其他
其他需要考虑的准则
- 将目录名称、文件名和文件路径用一对反引号括起来。
- 不要将列表项直接放在标题下；在列表之前添加介绍性句子或短语。
- 避免使用粗体文本。使用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 %}}
Use [`hugo.IsServer`] instead.
[`hugo.IsServer`]: /functions/hugo/isserver/
{{% /deprecated-in %}}
已渲染
eturl
使用嵌入式模板 URL (eturl) 短代码来插入嵌入式模板源代码的绝对 URL。短代码接受一个参数，即模板的基本文件名（省略文件扩展名）。
This is a link to the [embedded alias template].
[embedded alias template]: {{% eturl alias %}}
已渲染
这是指向 嵌入式别名模板的链接。
new-in
使用“new-in”短代码来指示新功能
{{< new-in 0.127.0 >}}
已渲染
v0.127.0 中的新功能注意
使用带有 {{% %}} 分隔符的 “note” 短代码来引起对重要内容的注意
{{% note %}}
Use the [`math.Mod`] function to control...
[`math.Mod`]: /functions/math/mod/
{{% /note %}}
已渲染
新功能
使用“new-in”短代码来指示新功能
{{< new-in 0.120.0 >}}如果指定的版本早于基于主版本和次版本差异的预定义阈值，“新功能”标签将被隐藏。请参阅 详情。
已弃用的功能
使用“deprecated-in”短代码来指示某个功能已弃用
{{% deprecated-in 0.120.0 %}}
Use [`hugo.IsServer`] instead.
[`hugo.IsServer`]: /functions/hugo/isserver/
{{% /deprecated-in %}}当弃用函数或方法时，请将其添加到 front matter 中
---
expiryDate: "2024-10-30"
---+++
expiryDate = '2024-10-30'
+++{
"expiryDate": "2024-10-30"
}
将 expiryDate 设置为自弃用之日起一年，并添加一个简短的 front matter 注释来解释此设置。
GitHub 工作流程
使用此工作流程创建和提交拉取请求。
- 步骤 1
- Fork 文档仓库。
- 步骤 2
- 克隆您的 fork。
- 步骤 3
- 创建一个新的分支，分支名应具有描述性，并包含相应的 issue 编号（如果有）。
git checkout -b restructure-foo-page-99999
- 步骤 4
- 进行更改。
- 步骤 5
- 在本地构建站点以预览您的更改。
- 步骤 6
- 提交您的更改，并附上描述性的提交消息
- 在第一行提供摘要，通常不超过 50 个字符，后跟一个空行。
- 可选地，提供详细描述，其中每行不超过 80 个字符，后跟一个空行。
- 可选地，添加一个或多个 “Fixes” 或 “Closes” 关键字，每个关键字单独一行，引用此更改解决的 issue。
例如
git commit -m "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
- 访问 文档仓库 并创建拉取请求 (PR)。
- 步骤 9
- 项目维护者将审查您的 PR，并可能要求进行更改。在维护者合并您的 PR 后，您可以删除您的分支。