編寫新主題

本頁面介紹如何為 Kubernetes 文件建立新主題。

準備工作

按照“提交 PR”中的說明，為 Kubernetes 文件建立一個倉庫的 fork。

選擇頁面型別

在準備編寫新主題時，請考慮哪種頁面型別最適合您的內容。

建立新頁面

為每個新頁面使用內容型別。文件網站提供模板或Hugo 樣板檔案來建立新的內容頁面。要建立新型別頁面，請執行hugo new並指定您要建立的檔案路徑。例如：

hugo new docs/concepts/my-first-concept.md

選擇標題和檔名

選擇一個包含您希望搜尋引擎找到的關鍵字的標題。建立使用標題中單詞並用連字元分隔的檔名。例如，標題為“使用 HTTP 代理訪問 Kubernetes API”的主題，其檔名是http-proxy-access-api.md。您無需在檔名中包含“kubernetes”，因為“kubernetes”已在主題的 URL 中，例如：

   /docs/tasks/extend-kubernetes/http-proxy-access-api/

在 front matter 中新增主題標題

在您的主題中，在front matter中放置一個title欄位。front matter 是頁面頂部三條短橫線之間的 YAML 塊。示例如下：

---
title: Using an HTTP Proxy to Access the Kubernetes API
---

選擇目錄

根據您的頁面型別，將新檔案放在以下某個目錄的子目錄中：

• /content/en/docs/tasks/
• /content/en/docs/tutorials/
• /content/en/docs/concepts/

您可以將檔案放在現有子目錄中，也可以建立新子目錄。

將主題放置在目錄中

目錄是根據文件源的目錄結構動態生成的。/content/en/docs/下的頂級目錄建立頂級導航，子目錄各自在目錄中擁有條目。

每個子目錄都有一個_index.md檔案，它代表了給定子目錄內容的“主頁”。_index.md不需要模板。它可以包含關於子目錄中主題的概述內容。

目錄中的其他檔案預設按字母順序排序。這幾乎不是最佳排序方式。要控制子目錄中主題的相對排序，請將weight: front matter 鍵設定為一個整數。通常，我們使用 10 的倍數，以便將來新增主題。例如，權重為10的主題將排在權重為20的主題之前。

在主題中嵌入程式碼

如果您想在主題中包含一些程式碼，可以使用 Markdown 程式碼塊語法直接在檔案中嵌入程式碼。這推薦用於以下情況（非詳盡列表）：

• 程式碼顯示了命令的輸出，例如 kubectl get deploy mydeployment -o json | jq '.status'。
• 程式碼不夠通用，使用者無法嘗試。例如，您可以嵌入建立 Pod 的 YAML 檔案，該 Pod 依賴於特定的FlexVolume實現。
• 程式碼是不完整的示例，因為其目的是突出較大檔案的一部分。例如，在描述自定義RoleBinding的方法時，您可以在主題檔案中直接提供一個簡短的片段。
• 由於其他原因，程式碼不適合使用者嘗試。例如，在描述如何使用kubectl edit命令將新屬性新增到資源時，您可以提供一個僅包含要新增屬性的簡短示例。

包含其他檔案的程式碼

在主題中包含程式碼的另一種方法是建立一個新的、完整的示例檔案（或一組示例檔案），然後從您的主題中引用該示例。當示例是通用的且可重用，並且您希望讀者自己嘗試時，請使用此方法包含示例 YAML 檔案。

新增新的獨立示例檔案（如 YAML 檔案）時，請將程式碼放在<LANG>/examples/子目錄之一中，其中<LANG>是主題的語言。在您的主題檔案中，使用code_sample短程式碼

{{% code_sample file="<RELPATH>/my-example-yaml>" %}}

其中<RELPATH>是相對於examples目錄的要包含檔案的路徑。以下 Hugo 短程式碼引用了位於/content/en/examples/pods/storage/gce-volume.yaml的 YAML 檔案。

{{% code_sample file="pods/storage/gce-volume.yaml" %}}

展示如何根據配置檔案建立 API 物件

如果您需要演示如何根據配置檔案建立 API 物件，請將配置檔案放在<LANG>/examples下的某個子目錄中。

在您的主題中，顯示此命令：

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

有關使用此技術的某個主題的示例，請參閱“執行單個例項的無狀態應用程式”。

向主題新增影像

將影像檔案放在/images目錄中。首選的影像格式是 SVG。

下一步

• 瞭解如何使用頁面內容型別。
• 瞭解如何建立拉取請求。