Kubernetes 文件

本儲存庫包含用於建置 Kubernetes 網站及文件的網站資源。歡迎您參與並貢獻內容！

• 貢獻文件
• README 在地化

使用本儲存庫

您可以使用 Hugo（擴展版）在本機執行網站，或透過容器化環境運行。我們強烈建議使用容器環境，因為這能確保與正式網站的部署環境保持一致。

前置需求

使用本儲存庫，您需要在本機安裝以下軟體：

• npm
• Go
• Hugo（擴展版）
• 容器執行環境，例如 Docker。

[!NOTE] 請確認您安裝的 Hugo 擴展版本與 netlify.toml 檔案中 HUGO_VERSION 環境變數指定的版本一致。

開始之前，請先安裝相依套件。接著複製儲存庫並進入目錄：

git clone https://github.com/kubernetes/website.git
cd website

Kubernetes 網站使用 Docsy Hugo 主題，可透過 npm 安裝。

您也可以下載預先設定好的開發容器映像檔，其中已包含 Hugo 和 Docsy。

此外，Kubernetes 網站也使用 Git 子模組來管理用於產生參考文件的工具。

Windows

# 取得子模組相依套件
git submodule update --init --recursive --depth 1

Linux / 其他 Unix

# 取得子模組相依套件
make module-init

使用容器執行網站

若要在容器中建置網站，請執行以下指令：

# 您可以將 $CONTAINER_ENGINE 設定為任何類似 Docker 的容器工具名稱

# 轉譯完整網站
make container-serve

# 僅轉譯特定語言（例如英文）
make container-serve segments=en

# 轉譯多種語言（例如英文和韓語）
make container-serve segments=en,ko

💡 提示： 使用 Hugo segments 只會轉譯所選的語言，可以加快本機預覽轉譯速度。

如果出現錯誤，可能表示 Hugo 容器沒有足夠的運算資源。要解決此問題，請增加 Docker 在您的機器上可使用的 CPU 與記憶體資源（macOS 和 Windows）。

開啟瀏覽器並前往 http://localhost:1313 查看網站。當您修改原始檔案時，Hugo 會自動更新網站並重新整理瀏覽器。

使用 Hugo 在本地執行網站

若要安裝相依套件、部署並在本機測試網站，請執行：

• macOS 和 Linux

  npm ci
  
  # 轉譯完整網站（預設）
  make serve
  
  # 僅轉譯特定語言
  make serve segments=en
  
  # 轉譯多種語言
  make serve segments=en,ko
  

💡 提示： Hugo segments 定義在 hugo.toml 中，將轉譯範圍限制在特定語言，可加快網站的轉譯速度。

• Windows (PowerShell)

  npm ci
  hugo.exe server --buildFuture --environment development
  

本機 Hugo 伺服器會在連接埠 1313 啟動。開啟瀏覽器並前往 http://localhost:1313 查看網站。當您修改原始檔案時，Hugo 會自動更新網站並重新整理瀏覽器。

建置 API 參考頁面

位於 content/en/docs/reference/kubernetes-api 的 API 參考頁面，是根據 Swagger 規格（亦稱為 OpenAPI 規格），並使用 https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs 產生。

若要為新的 Kubernetes 發行版本更新參考頁面，請依照以下步驟操作：

1. 取得 api-ref-generator 子模組：

   git submodule update --init --recursive --depth 1
   

2. 更新 Swagger 規格：

   curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json
   

3. 在 api-ref-assets/config/ 目錄中，調整 toc.yaml 和 fields.yaml 使其反映新版本的變更。

4. 接著建置頁面：

   make api-reference
   

   您可以透過使用容器映像檔建置並啟動網站，在本機測試結果：

   make container-image
   make container-serve
   

   在瀏覽器中前往 http://localhost:1313/docs/reference/kubernetes-api/ 查看 API 參考文件。

5. 當新的 API 變更已完整反映在 toc.yaml 和 fields.yaml 設定檔中後，請建立 Pull Request，提交新產生的 API 參考頁面。

疑難排解

如果在本機執行網站時遇到任何問題，請參閱貢獻文件的疑難排解章節。

參與 SIG Docs

在社群頁面上了解更多關於 SIG Docs Kubernetes 社群和會議資訊。

您也可以透過以下方式聯繫本專案的維護者：

• Slack
  • 取得 Slack 邀請
• 社群 Mailing List

貢獻文件

您可以點擊畫面右上角的 Fork 按鈕，在您的 GitHub 帳號中建立本儲存庫的分叉副本。此副本稱為 fork。您可以在 fork 中進行任何需要的修改；當準備好將變更提交給我們時，請到您的 fork 建立新的 pull request，讓我們知道您的修改。

Pull request 建立後，Kubernetes 的審查者會負責提供清楚且具體的回饋。身為 pull request 的作者，您有責任依據 Kubernetes 審查者提供的回饋更新您的 pull request。

請注意，您可能會收到多位 Kubernetes 審查者的回饋，也可能收到並非最初指派審查者所提供的回饋。

此外，在某些情況下，審查者可能會在需要時請 Kubernetes 技術審查者進行技術審查。審查者會盡力及時提供回饋，但回應時間可能會因實際情況而有所不同。

如需更多關於貢獻 Kubernetes 文件的資訊，請參閱：

• 貢獻 Kubernetes 文件
• 頁面內容類型
• 文件風格指南
• Kubernetes 文件在地化
• Kubernetes 文件簡介

新貢獻者大使

如果您在貢獻過程中的任何階段需要協助，新貢獻者大使是很好的聯繫窗口。他們是 SIG Docs 的 approver，職責之一是指導新貢獻者，並協助他們完成前幾個 pull request。聯繫新貢獻者大使的最佳方式是透過 Kubernetes Slack。目前 SIG Docs 的新貢獻者大使如下：

各語言在地化 README 列表

行為準則

參與 Kubernetes 社群須遵守 CNCF 行為準則。

感謝您

Kubernetes 仰賴社群的參與以持續發展，感謝您對我們網站與文件所做的貢獻！