本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
為本指南做出貢獻
任何人都可以為最佳實務指南做出貢獻。EKS 最佳實務指南是以 GitHub 上的 AsciiDoc 格式撰寫。
現有參與者的摘要
-
bpg-docs.code-workspace使用 VS 程式碼開啟 ，以自動安裝 AsciiDoc 延伸模組。 -
進一步了解 Visual Studio Marketplace 上的 AsciiDoc 延伸
模組。
-
-
AWS Docs 網站的來源檔案存放在
latest/bpg -
語法與 Markdown 非常相似。
-
檢閱 AsciiDoctor 文件中的語法參考
。
-
-
文件平台只會部署
latest/bpg/images。每個指南區段都有符號連結，可返回此目錄。例如，latest/bpg/networking/images指向latest/bpg/images。
設定本機編輯環境
如果您打算經常編輯指南，請設定本機編輯環境。
叉和複製儲存庫
您需要熟悉 git、 github和文字編輯器。如需有關開始使用 git和 的資訊github，請參閱 GitHub 文件中的 GitHub 帳戶入門
開啟 VS 程式碼工作區
AWS 建議使用 Microsoft 的 Visual Studio Code 來編輯指南。如需 VS 程式碼的詳細資訊，請參閱 Visual Studio 程式碼文件中的下載 Visual Studio 程式碼
-
開啟 VS 程式碼。
-
從複製的儲存庫開啟
bpg-docs.code-workspace檔案。 -
如果這是您第一次開啟此工作區，請接受 提示來安裝 AsciiDoc 延伸模組。此副檔名會檢查 AsciiDoc 檔案的語法，並產生即時預覽。
-
瀏覽至
latest/bpg目錄。此目錄會保留部署至 AWS 文件網站的來源檔案。來源檔案依指南區段組織，例如「安全性」或「網路」。
編輯檔案
-
在編輯器中開啟檔案。
-
檢視 AsciiDoc 語法，了解如何建立標題、連結和清單。
-
您可以使用 Markdown 語法來格式化文字、建立清單和標題。您無法使用 Markdown 語法建立連結。
-
-
開啟頁面的即時預覽。
-
首先，按
ctrl-k或cmd-k（取決於鍵盤）。第二，按v。這會在分割檢視中開啟預覽。
-
AWS 建議使用功能分支來組織您的變更。了解如何使用 git 建立分支。
提交提取請求
您可以從 GitHub 網站或 GitHub cli 建立提取請求。
了解如何使用 GitHub 網站從叉建立提取請求
了解如何使用 GitHub cli 建立提取請求
使用 github.dev Web 型編輯器
github.dev Web 型編輯器是以 VS 程式碼為基礎。這是編輯多個檔案和預覽內容的好方法，無需任何設定。
它支援 AsciiDoc 延伸模組。您可以使用 GUI 執行 git 操作。Web 型編輯器沒有執行命令的 shell 或終端機。
您必須擁有 GitHub 帳戶。如有需要，系統會提示您登入。
編輯單一頁面
您可以使用 GitHub 快速更新個別頁面。每個頁面底部都包含「📝在 GitHub 上編輯此頁面」連結。
-
導覽至本指南中您要編輯的頁面
-
按一下底部的「在 GitHub 上編輯此頁面」連結
-
按一下 GitHub 檔案檢視器右上角的編輯鉛筆圖示，或按
e -
編輯 檔案
-
使用「遞交變更...」按鈕提交您的變更。此按鈕會建立 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 應該是描述頁面內容的簡潔連字號字串。
-
在文字編輯器中開啟新頁面的來源檔案。
-
在檔案頂端，新增以下行。它應該位於第一個標題上方。
[#my-new-page]my-new-page將 取代為新頁面的頁面 ID。 -
儲存檔案。
注意
頁面 IDs 在整個文件網站上必須是唯一的。如果您嘗試使用現有的頁面 ID，您將會收到建置錯誤。
建立新頁面
了解如何建立新的頁面並更新 內容的指南資料表。
建立頁面中繼資料
-
決定頁面標題和頁面簡短標題。頁面短標題是選用的，但如果頁面標題超過幾個字，則建議使用。
-
判斷頁面的 ID。這在 EKS 最佳實務指南中必須是唯一的。慣例是使用所有小寫，並將單字與 分開
-。 -
視需要在資料夾中建立新的 asciidoc 檔案，並將下列文字新增至 檔案：
【."topic"】 【#<page-id>】 = <page-title> ：info_titleabbrev：<page-short-title>
例如
【."topic"】 【#scalability】 = EKS 可擴展性最佳實務：info_titleabbrev：可擴展性
新增至目錄
-
開啟 目錄中父頁面的檔案。對於新的最上層指南區段，父檔案為
book.adoc。 -
在父檔案底部，更新並插入下列指令：
包含：：<new-filename>【leveloffset=+1】
針對範例，
包括：：dataplane.adoc【leveloffset=+1】
插入映像
-
尋找您正在編輯之頁面的影像字首。檢閱 檔案標題中的
:imagesdir:屬性。如需範例，`:imagesdir: images/reliability/ -
將映像放在此路徑中，例如
latest/bpg/images/reliability -
為您的映像判斷適當的 alt-text。撰寫影像的簡短高階描述。例如，「具有三個可用區域的 VPC 圖表」是適當的 alt-text。
-
使用 alt-text 和映像檔案名稱更新下列範例。在所需位置插入 。
image：：<image-filename>【<image-alt-text>】
例如
image：：eks-data-plane-connectivity.jpeg【網路圖表】
使用 Vale 檢查樣式
建置本機預覽
-
在 Linux 或 MacOS
brew上使用 安裝asciidoctor工具-
了解如何在 AsciiDoctor 文件中安裝 asciidoctor cli
。 AsciiDoctor -
了解如何安裝沖煮套件管理員
。
-
-
開啟終端機，然後導覽至
latest/bpg/ -
執行
asciidoctor book.adoc-
檢閱任何語法警告和錯誤
-
-
開啟
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: <<page-id>>
Internal link: xref:page-id[Link text]映像
image::image-file.jpg[Alt text]
程式碼區塊
[source,python]
----
def hello_world():
print("Hello, World!")
----資料表
[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[]