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 後刪除你的分支。