CONTRIBUTE

文檔貢獻指南

介紹

我們歡迎任何對文檔的修正和改進。請注意，文檔位於一個獨立的資料庫中，與專案資料庫分開。

若您對現有文檔有修正或改進，請提交議題（issue）或拉取請求（pull request）至[文檔資料庫]。

若您為新功能提供文檔，請在提交功能的拉取請求時，將文檔更新一併提交至[專案資料庫]。

指導方針

Markdown 格式

請遵循以下指導方針：

  • 使用 ATX 標題，避免使用 setext 標題，標題層級限制於 2-4 級。
  • 使用 fenced code blocks，不要使用 indented code blocks。
  • 使用破折號（hyphen），而不是星號（asterisks），作為無序列表的符號。
  • 使用 note shortcode 來替代區塊引用。
  • 避免在 Markdown 文件中混用 raw HTML。
  • 不要將粗體文字用於標題或描述術語（dt）。
  • 刪除連續的空白行（最多可有兩行空白行）。
  • 移除行尾空格。

風格

請遵循 Google 的開發者文檔風格指南。

術語

在適當情況下，請連結 術語表，並在整個文檔中一致地使用這些術語。特別注意以下事項：

  • “front matter” 應為兩個字，除非您指的是設定檔中的某個配置項。
  • “home page” 應為兩個字。
  • “website” 應為一個字。
  • “standalone” 應為一個字，並且不加連字符。
  • 當指稱命令列旗標（flag）時，請使用 “flag” 而不是 “option”。
  • 請將 “Markdown” 改為首字母大寫。
  • 當作為形容詞使用時，“open-source” 應加連字符。

頁面標題和標題

請遵循以下頁面標題和標題的指導方針：

  • 使用句子式大小寫（sentence-style capitalization）。
  • 避免在標題和頁面標題中使用格式化的字串。
  • 簡短為佳。

使用現在式主動語態

在軟體文檔中，某些情況下無法避免使用被動語態。請儘可能使用主動語態。

不推薦 → 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.

標題層級 6

標題層級 6 以 dt 元素的方式顯示，這是為了支援 術語表 並可以鏈接術語。

函數和方法描述

在向 functions 或 methods 頁面添加函數或方法描述時，應以 “Returns” 開頭。對於返回布林值的函數，應以 “Reports whether” 開頭。

範例：

  • Returns the URL aliases as defined in front matter.
  • Reports whether the given page is in the given section.

其他注意事項

以下是其他需要考量的指導方針：

  • 不要將列表項直接置於標題下，應在列表前先放置一句介紹性句子或短語。
  • 避免使用 粗體 文字，使用 note shortcode 來突出顯示重要內容。
  • 除非語法上需要清晰，不要將描述術語（dt）放入反引號中。
  • 請勿使用 Hugo 的 ref 或 relref shortcode，我們會使用鏈接渲染掛載來解析並驗證鏈接目的地（包括片段）。
  • 簡短為佳。如果有多種做法，應描述當前最佳的做法。避免使用 “你也可以…” 或 “在舊版本中，你必須…” 這樣的句子。
  • 當包含代碼範例時，請使用簡短的片段來展示概念。
  • Hugo 的用戶社群是全球性的，盡可能使用 基礎英語。

代碼範例

縮排代碼時請使用兩個空格。在展示模板代碼時，開放的操作界限符號應在前面留有空格，並在關閉的操作界限符號前加上空格。

Fenced Code Blocks

當使用 fenced code blocks 時，請始終加入語言代碼：

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

渲染結果：

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

Shortcode 呼叫

使用以下語法在代碼範例中包含 shortcode 呼叫：

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

渲染結果：

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

站點配置

使用 code-toggle shortcode 來包含站點配置範例：

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

渲染結果：

hugo.
      
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"
}

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

渲染結果：

content/posts/my-first-post.md
      
---
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 shortcode 來顯示其他需要檔案名稱的程式碼範例：

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

渲染後：

layouts/_default/single.html
{{ 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`]。

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

渲染後：

eturl

使用內嵌模板 URL（eturl）短代碼來插入嵌入模板的原始碼絕對 URL。此短代碼需要一個參數，即模板的基檔名（省略副檔名）：

這是一個指向 [內嵌別名模板] 的鏈接。

[內嵌別名模板]: {{% eturl alias %}}

渲染後：

這是一個指向 內嵌別名模板 的鏈接。

new-in

使用 “new-in” 短代碼來標示新功能：

{{< new-in 0.127.0 >}}

渲染後：

New in v0.127.0

note

使用 “note” 短代碼與 {{% %}} 分隔符來引起注意，強調重要內容：

{{% note %}}
請使用 [`math.Mod`] 函數來控制...

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

渲染後：

新功能

使用 “new-in” 短代碼來標示新功能：

content/something/foo.md
{{< new-in 0.120.0 >}}

“new-in” 標籤會在版本號小於某個預設閾值（根據主要和次要版本差異）時隱藏。更多詳情請參見 細節。

不推薦使用的功能

使用 “deprecated-in” 短代碼來標示某個功能已不推薦使用：

content/something/foo.md
{{% deprecated-in 0.120.0 %}}
請改用 [`hugo.IsServer`]。

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

當要標示某個函數或方法被不推薦使用時，請將以下內容加入前置資訊：

content/something/foo.md
      
---
expiryDate: "2024-10-30"
---
+++
expiryDate = '2024-10-30'
+++
{
   "expiryDate": "2024-10-30"
}

將 expiryDate 設定為自不推薦使用日期起一年的日期，並添加簡短的前置資訊註解來解釋這個設定。

GitHub 工作流程

使用這個工作流程來創建和提交 pull requests。

步驟 1
Fork [文件庫]。
步驟 2
克隆你的 fork。
步驟 3
創建一個新的分支，分支名稱應該具有描述性，且如果有對應的問題，請包括其編號：
git checkout -b restructure-foo-page-99999
步驟 4
進行變更。
步驟 5
本地構建網站來預覽你的變更。
步驟 6
使用描述性的提交訊息提交你的變更：
  • 第一行提供摘要，通常不超過 50 個字，後接空白行。
  • 選擇性地，提供詳細描述，每行不超過 80 個字，後接空白行。
  • 選擇性地，添加一個或多個 “Fixes” 或 “Closes” 關鍵字，每行一個，引用本變更解決的 [問題]。

例如：

git commit -m "重構分類頁面

這個變更將分類頁面重構，按邏輯分割話題，每個話題會有一個或多個範例。

Fixes #9999
Closes #9998"

當然，這是您請求的內容翻譯，使用正體中文：

步驟 7
將新的分支推送到您的文件庫的分支。
步驟 8
訪問 [文件庫] 並創建一個拉取請求（PR）。
步驟 9
項目維護者將審查您的 PR，並可能要求進行修改。在維護者合併您的 PR 後，您可以刪除您的分支。
模板類型 ToCSS