文件風格指南

本頁面提供了 Kubernetes 文件的寫作風格指南。這些是指南，不是規則。請自行判斷，並隨時透過 pull request 提出對本檔案的修改建議。

有關為 Kubernetes 文件建立新內容的更多資訊，請閱讀《文件內容指南》。

風格指南的更改由 SIG Docs 作為一個整體進行。要提議更改或新增內容，請將其新增到即將舉行的 SIG Docs 會議議程中，並參加會議以參與討論。

語言

Kubernetes 文件已被翻譯成多種語言（參見本地化 README）。

為不同語言本地化文件的方法在《本地化 Kubernetes 文件》中有描述。

英文文件使用美式英語拼寫和語法。

文件格式標準

API 物件使用大駝峰式命名（Upper Camel Case）

當您專門提及與 API 物件互動時，請使用 大駝峰式命名（UpperCamelCase），也稱為 Pascal 命名。您可能會在 API 參考中看到不同的寫法，例如“configMap”。在撰寫一般性文件時，最好使用大駝峰式命名，稱之為“ConfigMap”。

當您一般性地討論 API 物件時，請使用句子風格大小寫。

以下示例著重於大小寫。有關格式化 API 物件名稱的更多資訊，請參閱有關程式碼風格的相關指南。

佔位符使用尖括號

佔位符使用尖括號。告知讀者佔位符代表什麼，例如

顯示 Pod 資訊

kubectl describe pod <pod-name> -n <namespace>

如果 Pod 的名稱空間是 default，則可以省略 '-n' 引數。

使用者介面元素使用粗體

斜體用於定義或介紹新術語

檔名、目錄和路徑使用程式碼風格

在引號內使用國際標點符號標準

行內程式碼格式化

行內程式碼、命令使用程式碼風格

對於 HTML 文件中的行內程式碼，請使用 <code> 標籤。在 Markdown 文件中，請使用反引號 (`)。但是，API kinds（如 StatefulSet 或 ConfigMap）則按原樣編寫（無反引號）；這允許使用所有格撇號。

物件欄位名和名稱空間使用程式碼風格

Kubernetes 命令工具和元件名稱使用程式碼風格

以元件工具或元件名稱開頭句子

使用通用描述符代替元件名稱

字串和整數字段值使用普通樣式

對於字串或整數型別的欄位值，請使用普通樣式，不帶引號。

然而，如果可能引起讀者混淆，請考慮給值加上引號，例如將其與 API kind 混淆。

引用 Kubernetes API 資源

本節討論如何在文件中引用 API 資源。

關於“資源”的澄清

Kubernetes 使用“resource”一詞來指代 API 資源。例如，URL 路徑 /apis/apps/v1/namespaces/default/deployments/my-app 代表 "default"名稱空間中名為 "my-app" 的 Deployment。在 HTTP 術語中，namespace 就是一種資源——就像所有 Web URL 都標識一個資源一樣。

Kubernetes 文件也使用“resource”來討論 CPU 和記憶體的請求與限制。通常最好將 API 資源稱為“API resources”；這有助於避免與 CPU 和記憶體資源或與其他型別的資源混淆。

如果您使用的是資源名稱的小寫複數形式，例如 deployments 或 configmaps，請提供額外的書面上下文以幫助讀者理解您的意思。如果您在可以使用大駝峰式名稱的上下文中使用了該術語，並且存在歧義的風險，請考慮使用大駝峰式名稱的 API kind。

何時使用 Kubernetes API 術語

不同的 Kubernetes API 術語是

• API kinds：API URL 中使用的名稱（例如 pods、namespaces）。API kinds 有時也稱為resource types。
• API resource：API kind 的單個例項（例如 pod、secret）。
• Object：用作“意圖記錄”的資源。物件是您叢集特定部分的期望狀態，Kubernetes 控制平面會嘗試維護。Kubernetes API 中的所有物件也都是資源。

為清晰起見，您可以在引用 Kubernetes 文件中的 API 資源時新增“resource”或“object”。例如：寫“a Secret object”而不是“a Secret”。如果僅從大小寫就能清楚，則無需新增額外的詞。

當更改有助於避免誤解時，請考慮重新措辭。一種常見的情況是當您想以 API kind 開頭一個句子時，例如“Secret”；因為英語和其他語言在句子開頭都會大寫，所以讀者無法區分您是指 API kind 還是通用概念。改寫可以提供幫助。

API 資源名稱

始終使用 大駝峰式命名（UpperCamelCase）（也稱為 PascalCase）來格式化 API 資源名稱。請勿使用程式碼格式來編寫 API kinds。

不要將 API 物件名稱拆分成單獨的單詞。例如，使用 PodTemplateList，而不是 Pod Template List。

有關 PascalCase 和程式碼格式的更多資訊，請參閱有關API 物件使用大駝峰式命名和行內程式碼、命令和 API 物件使用程式碼風格的相關指南。

有關 Kubernetes API 術語的更多資訊，請參閱有關Kubernetes API 術語的相關指南。

程式碼片段格式

不要包含命令提示符

分離命令和輸出

驗證 Pod 是否在你選擇的節點上執行。

kubectl get pods --output=wide

輸出類似於：

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

版本化 Kubernetes 示例

包含版本資訊的程式碼示例和配置示例應與伴隨文字保持一致。

如果資訊是特定於版本的，則 Kubernetes 版本需要在任務模板或教程模板的prerequisites部分進行定義。頁面儲存後，prerequisites部分將顯示為Before you begin。

要指定任務或教程頁面的 Kubernetes 版本，請在頁面的 front matter 中包含 min-kubernetes-server-version。

如果示例 YAML 位於獨立檔案中，請查詢並審查包含它的主題作為參考。驗證使用獨立 YAML 的任何主題是否已定義適當的版本資訊。如果獨立 YAML 檔案未被任何主題引用，請考慮刪除它而不是更新它。

例如，如果您正在編寫與 Kubernetes 版本 1.8 相關的教程，您的 markdown 檔案的 front-matter 應如下所示

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

在程式碼和配置示例中，請勿包含有關其他版本的註釋。請注意不要在您的示例中包含不正確的陳述作為註釋，例如

apiVersion: v1 # earlier versions use...
kind: Pod
...

公式和方程

您可以使用 Docsy 對圖表和公式的支援。

例如：\\(\frac{7}{9} \sqrt{K^8 s}\\)，渲染為 \(\frac{7}{9} \sqrt{K^8 s}\)。

如果合理，請優先使用行內公式，但如果可能有助於讀者理解，您可以使用 math 塊。

閱讀 Docsy 指南，瞭解您需要更改頁面中的哪些內容來啟用支援；如果您遇到問題，請將 math: true 新增到頁面的front matter中（即使您認為自動啟用應該足夠了，也可以這樣做）。

Kubernetes.io 詞彙表

一份 Kubernetes 特定術語和單詞列表，應在整個站點中保持一致使用。

短程式碼（Shortcodes）

Hugo Shortcodes 有助於建立不同層次的修辭吸引力。我們的文件在此類別中支援三種不同的短程式碼：Note {{< note >}}，Caution {{< caution >}}，和 Warning {{< warning >}}。

1. 將文字用開啟和關閉的短程式碼括起來。

2. 使用以下語法應用樣式

   {{< note >}}
   No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.)
   {{< /note >}}
   

   輸出為：

   注意

   您選擇的字首與標籤的文字相同。

注意

使用 {{< note >}} 來突出顯示提示或可能有助於瞭解的資訊。

例如

{{< note >}}
You can _still_ use Markdown inside these callouts.
{{< /note >}}

輸出為：

您可以在列表中使用 {{< note >}}

1. Use the note shortcode in a list

1. A second item with an embedded note

   {{< note >}}
   Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues).
   {{< /note >}}

1. A third item in a list

1. A fourth item in a list

輸出為：

1. 在列表中使用 note 短程式碼

2. 包含嵌入式 note 的第二個專案

   注意

   Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues).
   

3. 列表中的第三項

4. 列表中的第四項

注意

使用 {{< caution >}} 來引起注意重要的資訊，以避免陷阱。

例如

{{< caution >}}
The callout style only applies to the line directly above the tag.
{{< /caution >}}

輸出為：

警告

使用 {{< warning >}} 來指示危險或必須遵循的資訊。

例如

{{< warning >}}
Beware.
{{< /warning >}}

輸出為：

常見的短程式碼問題

有序列表

短程式碼會中斷編號列表，除非您在通知和標籤前縮排四個空格。

例如

1. Preheat oven to 350˚F

1. Prepare the batter, and pour into springform pan.
   {{< note >}}Grease the pan for best results.{{< /note >}}

1. Bake for 20-25 minutes or until set.

輸出為：

1. 烤箱預熱至 350˚F

2. 準備麵糊，倒入彈簧扣烤盤。

   注意

   給烤盤塗油以獲得最佳效果。

3. 烘烤 20-25 分鐘或直至凝固。

包含語句

包含語句中的短程式碼會破壞構建。您必須將其插入父文件中，在呼叫 include 之前和之後。例如

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Markdown 元素

換行

使用單個換行來分隔塊級內容，如標題、列表、影像、程式碼塊等。例外情況是二級標題，應使用兩個換行。二級標題緊跟在一級標題（或標題）之後，前面沒有任何段落或文字。雙倍行距有助於在程式碼編輯器中更好地視覺化內容的整體結構。

在 Markdown 源中適當地手動換行段落。由於 git 工具和 GitHub 網站逐行生成檔案 diff，手動換行長行有助於審閱者輕鬆找出 PR 中所做的更改並提供反饋。它還有助於下游本地化團隊，因為人們會逐行跟蹤上游更改。換行可以在句末或標點符號處發生。一個例外是 Markdown 連結或短程式碼應保持在一行。

標題和副標題

訪問此文件的讀者可能會使用螢幕閱讀器或其他輔助技術（AT）。螢幕閱讀器是線性輸出裝置，它們一次輸出頁面上的一個專案。如果頁面內容很多，您可以使用標題為頁面提供內部結構。良好的頁面結構有助於所有讀者輕鬆導航頁面或篩選感興趣的主題。

段落

連結

列表

將列表中相互關聯且需要按特定順序出現或指示多個專案之間相關性的專案分組。當螢幕閱讀器遇到列表時——無論是有序列表還是無序列表——它會向用戶宣佈有一個列表項組。然後使用者可以使用箭頭鍵在列表中的各個專案之間上下移動。網站導航連結也可以標記為列表項；畢竟它們只是相關連結的集合。

• 如果列表中的一個或多個專案是完整的句子，則在列表項末尾加上句點。為了保持一致性，通常所有專案都應該是完整的句子，或者都不是。

  注意

  作為不完整介紹性句子一部分的有序列表可以小寫，並像每個專案都是介紹性句子的一部分一樣進行標點。

• 有序列表使用數字一（1.）。

• 無序列表使用（+）、（*）或（-）。

• 在每個列表項後留一個空行。

• 使用四個空格縮排巢狀列表（例如，⋅⋅⋅⋅）。

• 列表項可能包含多個段落。列表項中的每個後續段落都必須縮排四個空格或一個製表符。

表

資料表的語義目的是呈現表格資料。視力正常的使用者可以快速掃描表格，但螢幕閱讀器會逐行讀取。表格標題用於為資料表建立描述性標題。輔助技術（AT）使用 HTML 表格標題元素在頁面結構中向用戶識別表格內容。

• 使用 Hugo 表格短程式碼新增表格標題。

內容最佳實踐

本節包含關於清晰、簡潔和一致內容的建議最佳實踐。

使用現在時

例外：如果需要傳達正確的含義，請使用將來時或過去時。

使用主動語態

例外：如果主動語態會導致笨拙的結構，請使用被動語態。

使用簡單直接的語言

使用簡單直接的語言。避免使用不必要的短語，例如說“請”。

將讀者稱為“您”

避免使用拉丁語

優先使用英語術語而非拉丁縮寫。

例外：使用 "etc." 表示 et cetera。

要避免的模式

避免使用“我們”

在句子中使用“我們”可能會令人困惑，因為讀者可能不知道他們是否屬於您所描述的“我們”。

避免使用行話和習語

一些讀者以英語為第二語言。避免使用行話和習語，以幫助他們更好地理解。

避免關於未來的陳述

避免做出承諾或暗示未來。如果您需要談論 alpha 功能，請將文字放在一個將它標識為 alpha 資訊的標題下。

此規則的一個例外是關於宣佈的已棄用項，旨在在未來版本中移除的文件。例如，已棄用的 API 遷移指南。

避免使用過時的陳述

避免使用“目前”和“新”等詞。今天的新功能可能在幾個月後就不再被認為是新的了。

避免使用假設特定理解水平的詞語

避免使用“僅僅”、“簡單”、“容易”等詞。這些詞沒有增加價值。

EditorConfig 檔案

Kubernetes 專案維護了一個 EditorConfig 檔案，該檔案在 VS Code 等文字編輯器中設定了通用的樣式偏好。如果您想確保您的貢獻與專案的其他部分保持一致，可以使用此檔案。要檢視該檔案，請參閱倉庫根目錄中的.editorconfig。

下一步

• 瞭解如何編寫新主題。
• 瞭解如何使用頁面模板。
• 瞭解自定義 hugo 短程式碼。
• 瞭解如何建立 pull request。