撰寫新主題
本頁說明如何為 Kubernetes 文件建立新主題。
開始之前
如開啟 PR中所述，建立 Kubernetes 文件儲存庫的分支。
選擇頁面類型
當您準備撰寫新主題時，請思考最適合您內容的頁面類型
| 類型 | 描述 |
|---|---|
| 概念 | 概念頁面說明 Kubernetes 的某些方面。例如，概念頁面可能會描述 Kubernetes Deployment 物件，並說明其在應用程式部署、擴展與更新時所扮演的角色。通常，概念頁面不包含步驟序列，而是提供任務或教學課程的連結。如需概念主題的範例，請參閱節點。 |
| 任務 | 任務頁面說明如何執行單一操作。目的是為讀者提供一系列步驟，讓他們在閱讀頁面時可以實際執行。任務頁面可以是短篇或長篇，前提是它始終專注於一個領域。在任務頁面中，可以將簡短的解釋與要執行的步驟混合在一起，但如果您需要提供冗長的解釋，則應在概念主題中執行。相關的任務與概念主題應互相連結。如需簡短任務頁面的範例，請參閱設定 Pod 以使用磁碟區進行儲存。如需較長任務頁面的範例，請參閱設定存活度與就緒度探測 |
| 教學課程 | 教學課程頁面說明如何達成將多個 Kubernetes 功能結合在一起的目標。教學課程可能會提供多個步驟序列，讓讀者在閱讀頁面時可以實際執行。或者，它可能會提供相關程式碼片段的說明。例如，教學課程可以提供程式碼範例的導覽。教學課程可以包含對所結合 Kubernetes 功能的簡短說明，但應連結至相關的概念主題，以深入解釋個別功能。 |
建立新頁面
為您撰寫的每個新頁面使用內容類型。文件網站提供範本或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 檔案，該檔案取決於特定的FlexVolume 實作。
- 程式碼是不完整的範例，因為其目的是突顯較大檔案的一部分。例如，在描述自訂RoleBinding的方式時，您可以直接在主題檔案中提供簡短的程式碼片段。
- 由於其他原因，程式碼不適合使用者試用。例如，在描述如何使用
kubectl edit命令將新屬性新增至資源時，您可以提供一個簡短的範例，其中僅包含要新增的屬性。
從另一個檔案包含程式碼
在主題中包含程式碼的另一種方法是建立新的完整範例檔案（或範例檔案群組），然後從您的主題參考範例。當範例是通用的且可重複使用，且您希望讀者自行試用時，請使用此方法來包含範例 YAML 檔案。
新增新的獨立範例檔案（例如 YAML 檔案）時，請將程式碼放在 <LANG>/examples/ 子目錄之一中，其中 <LANG> 是主題的語言。在您的主題檔案中，使用 code_sample Shortcode
{{% 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
注意
當將新的 YAML 檔案新增至<LANG>/examples 目錄時，請確保該檔案也包含在 <LANG>/examples_test.go 檔案中。當 PR 被提交時，網站的 Travis CI 會自動執行此測試案例，以確保所有範例都通過測試。如需使用此技術的主題範例，請參閱執行單一實例有狀態應用程式。
將圖片新增至主題
將圖片檔案放在 /images 目錄中。建議的圖片格式為 SVG。
下一步
- 瞭解使用頁面內容類型。
- 瞭解建立 Pull Request。