本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 本指南的貢獻
任何人都可以對最佳實務指南做出貢獻。EKS 最佳實務指南是以 GitHub 上的 AsciiDoc 格式撰寫。
## 現有參與者的摘要
+ [https://github.com/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace](https://github.com/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace) 使用 VS 程式碼開啟 ，以自動安裝 AsciiDoc 延伸模組。
+ 進一步了解 Visual Studio Marketplace 上的 [AsciiDoc 延伸](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode)模組。
+ AWS Docs 網站的來源檔案存放在 [https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg](https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg)
+ 語法與 Markdown 非常相似。
+ 檢閱 AsciiDoctor 文件中的[語法參考](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/)。
+ 文件平台只會部署 `latest/bpg/images`。每個指南區段都有返回此目錄的符號連結。例如， `latest/bpg/networking/images` 指向 `latest/bpg/images`。
## 設定本機編輯環境
如果您打算經常編輯指南，請設定本機編輯環境。
### 分叉並複製儲存庫
您需要熟悉 `git`、 `github`和文字編輯器。如需 `git`和 入門的資訊`github`，請參閱 [ GitHub 文件中的 GitHub 帳戶入門](https://docs.github.com/en/get-started/onboarding/getting-started-with-your-github-account)。 GitHub
1. 檢視 [ GitHub 上的 EKS 最佳實務指南](https://github.com/aws/aws-eks-best-practices)。
1. 建立專案儲存庫的分支。了解如何[在 GitHub 文件中授予儲存庫](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository)。 GitHub
1. 複製專案儲存庫的分支。了解如何[複製您的分叉儲存庫](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository)。
### 開啟 VS 程式碼工作區
AWS 建議使用 Microsoft 的 Visual Studio Code 來編輯指南。如需 VS 程式碼的詳細資訊，請參閱 [Visual Studio 程式碼文件中的下載](https://code.visualstudio.com/download) Visual [Studio 程式碼](https://code.visualstudio.com/docs/getstarted/getting-started)和開始使用 Visual Studio 程式碼。
1. 開啟 VS Code。
1. 從複製的儲存庫開啟 `bpg-docs.code-workspace` 檔案。
1. 如果這是您第一次開啟此工作區，請接受 提示來安裝 AsciiDoc 延伸模組。此副檔名會檢查 AsciiDoc 檔案的語法，並產生即時預覽。
1. 瀏覽至 `latest/bpg`目錄。此目錄會保留部署至 AWS 文件網站的來源檔案。來源檔案依指南區段組織，例如「安全性」或「網路」。
### 編輯檔案
1. 在編輯器中開啟檔案。
+ 檢視 AsciiDoc 語法，了解如何建立標題、連結和清單。
+ 您可以使用 Markdown 語法來格式化文字、建立清單和標題。您無法使用 Markdown 語法建立連結。
1. 開啟頁面的即時預覽。
+ 首先，按 `ctrl-k`或 `cmd-k`（取決於鍵盤）。第二，按 `v`。這會在分割檢視中開啟預覽。
AWS 建議使用功能分支來組織您的變更。了解如何使用 git 建立分支。
### 提交提取請求
您可以從 GitHub 網站或 GitHub cli 建立提取請求。
了解如何使用 GitHub 網站[從分支建立提取請求](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)。
了解如何使用 GitHub cli [建立提取請求](https://cli.github.com/manual/gh_pr_create)。
## 使用 github.dev Web 型編輯器
`github.dev` Web 型編輯器是以 VS 程式碼為基礎。這是編輯多個檔案和預覽內容的好方法，無需任何設定。
它支援 AsciiDoc 延伸模組。您可以使用 GUI 執行 git 操作。Web 型編輯器沒有執行命令的 shell 或終端機。
您必須擁有 GitHub 帳戶。如有需要，系統會提示您登入。
[🚀 啟動 GitHub Web 型編輯器。](https://github.dev/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace?workspace=true)
## 編輯單一頁面
您可以使用 GitHub 快速更新個別頁面。每個頁面底部都包含「📝在 GitHub 上編輯此頁面」連結。
1. 導覽至本指南中您要編輯的頁面
1. 按一下底部的「在 GitHub 上編輯此頁面」連結
1. 按一下 GitHub 檔案檢視器右上角的編輯鉛筆圖示，或按 `e`
1. 編輯 檔案
1. 使用「遞交變更...」按鈕提交您的變更。此按鈕會建立 GitHub 提取請求。指南維護者將檢閱此提取請求。檢閱者將核准提取請求或請求變更。
## 檢視並設定頁面的 ID
此頁面說明如何檢視和設定頁面 ID。
頁面 ID 是可識別文件網站上每個頁面的唯一字串。當您在特定頁面上時，可以在瀏覽器的地址列中檢視頁面 ID。頁面 ID 用於 URL、檔案名稱和 ，以建立交叉參考連結。
例如，如果您正在檢視此頁面，瀏覽器地址列中的 URL 看起來會類似：
```
https://docs.aws.amazon.com/view-set-page-id.html
```
URL (`view-set-page-id`) 的最後一個部分是頁面 ID。
### 設定頁面 ID
建立新頁面時，您需要在來源檔案中設定頁面 ID。頁面 ID 應該是描述頁面內容的簡潔連字號字串。
1. 在文字編輯器中開啟新頁面的來源檔案。
1. 在檔案頂端，新增以下行。它應該位於第一個標題上方。
```
[#my-new-page]
```
`my-new-page` 將 取代為新頁面的頁面 ID。
1. 儲存檔案。
**注意**
頁面 IDs 在整個文件網站上必須是唯一的。如果您嘗試使用現有的頁面 ID，您會收到建置錯誤。
## 建立新頁面
了解如何建立新頁面並更新 內容的指南表格。
### 建立頁面中繼資料
1. 決定頁面標題和頁面簡短標題。頁面簡短標題是選用的，但如果頁面標題超過幾個字，則建議使用。
1. 判斷頁面的 ID。這在 EKS 最佳實務指南中必須是唯一的。慣例是使用所有小寫，並將單字與 分開`-`。
1. 視需要在資料夾中建立新的 asciidoc 檔案，並將下列文字新增至檔案：
**Example**
【."topic"】 【\$1】 = ：info\$1titleabbrev：
例如
**Example**
【."topic"】 【\$1scalability】 = EKS 可擴展性最佳實務：info\$1titleabbrev：可擴展性
### 新增至目錄
1. 開啟 目錄中父頁面的檔案。對於新的頂層指南區段，父檔案為 `book.adoc`。
1. 在父檔案底部，更新並插入下列指令：
**Example**
包括：：【leveloffset=\$11】
例如，
**Example**
包括：：dataplane.adoc【leveloffset=\$11】
## 插入映像
1. 尋找您正在編輯之頁面的影像字首。檢閱 檔案標題中的 `:imagesdir:` 屬性。如需範例， ``:imagesdir: images/reliability/`
1. 將您的映像放在此路徑中，例如 `latest/bpg/images/reliability`
1. 為您的映像決定適當的 alt-text。撰寫影像的簡短高階描述。例如，「具有三個可用區域的 VPC 圖表」是適當的 alt-text。
1. 使用 alt-text 和映像檔案名稱更新下列範例。在所需的位置插入 。
**Example**
image：：【】
例如
**Example**
image：：eks-data-plane-connectivity.jpeg【網路圖表】
## 使用 Vale 檢查樣式
1. [安裝 Vale CLI。](https://vale.sh/docs/vale-cli/installation/)
1. 執行 `vale sync`
1. 從 Visual Studio Marketplace 安裝 [Vale 延伸](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode)模組。
1. 重新啟動 VS 程式碼，並開啟 AsciiDoc 檔案
1. VS 程式碼會強調有問題的文字。了解如何在 VS Code 文件中使用[錯誤和警告](https://code.visualstudio.com/docs/editor/editingevolved#_errors-warnings)。
## 建置本機預覽
1. 在 Linux 或 MacOS `brew` 上使用 安裝`asciidoctor`工具
+ 了解如何在 [AsciiDoctor 文件中安裝 Asciidoctor cli](https://docs.asciidoctor.org/asciidoctor/latest/install/)。 AsciiDoctor
+ 了解如何[安裝 brew 套件管理員](https://brew.sh/index.html)。
1. 開啟終端機，然後導覽至 `latest/bpg/`
1. 執行 `asciidoctor book.adoc`
+ 檢閱任何語法警告和錯誤
1. 開啟`book.html`輸出檔案。
+ 在 MacOS 上，您可以執行 `open book.html` 在預設瀏覽器中開啟預覽。
## AsciiDoc Cheat Sheet
### 基本格式化
```
*bold text*
_italic text_
`monospace text`
```
### 標頭
```
= Document Title (Header 1)
== Header 2
=== Header 3
==== Header 4
===== Header 5
====== Header 6
```
### 清單
未排序的清單：
```
- Item 1
- Item 2
-- Subitem 2.1
-- Subitem 2.2
- Item 3
```
排序清單：
```
. First item
. Second item
.. Subitem 2.1
.. Subitem 2.2
. Third item
```
### 連結
```
External link: https://example.com[Link text]
Internal link: <>
Internal link: xref:page-id[Link text]
```
### 映像
```
image::image-file.jpg[Alt text]
```
### 程式碼區塊
```
[source,python]
----
def hello_world():
print("Hello, World!")
----
```
### 表格
[了解如何建置基本資料表。](https://docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/)
```
[cols="1,1"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 1, row 3
|Cell in column 2, row 3
|===
```
### 輔助
```
NOTE: This is a note admonition.
WARNING: This is a warning admonition.
TIP: This is a tip admonition.
IMPORTANT: This is an important admonition.
CAUTION: This is a caution admonition.
```
預覽版：
**注意**
這是筆記提醒。
### 包括
```
include::filename.adoc[]
```