本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 为本指南做出贡献
任何人都可以为最佳实践指南做出贡献。《EKS 最佳实践指南》的 AsciiDoc 格式为 GitHub。
## 现有贡献者摘要
+ [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 Code 打开，即可自动安装 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)。
1. 在上查看 [EKS 最佳实践指南 GitHub](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)。
1. 克隆您的项目仓库分支。了解如何[克隆您的分叉存储库](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository)。
### 打开 VS 代码工作区
AWS 建议使用微软提供的 Visual Studio 代码来编辑该指南。有关 VS Code 的更多信息，请参阅 V [isual Studio 代码文档中的下载](https://code.visualstudio.com/download) V [isual 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 网站[从 fork 创建拉取请求](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 基于网络的编辑器
`github.dev`基于 Web 的编辑器基于 VS Code。这是无需任何设置即可编辑多个文件和预览内容的好方法。
它支持该 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、文件名和创建交叉引用链接。
例如，如果您正在查看此页面，则浏览器地址栏中的网址将类似于：
```
https://docs.aws.amazon.com/view-set-page-id.html
```
网址 (`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**
[。” 主题 "] [\$1] =: info\$1titleabbrev: < > page-short-title
例如，
**Example**
[。” 主题 "] [\$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. 为您的图片确定合适的替代文本。为图像写一个简短的高级描述。例如，“具有三个可用区的 VPC 示意图” 是恰当的替代文本。
1. 使用替代文本和图像文件名更新以下示例。在所需位置插入。
**Example**
图片:: [< image-alt-text >]
例如，
**Example**
图片:: eks-data-plane-connectivity .jpeg [网络图]
## 向淡水河谷查询风格
1. [安装 Vale CLI。](https://vale.sh/docs/vale-cli/installation/)
1. 运行 `vale sync`
1. 从 Visual Studio Marketplace 安装[谷扩展程序](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode)。
1. 重启 VS Code，然后打开一个 AsciiDoc 文件
1. VS Code 在有问题的文本下划线。在 VS Code 文档中学习如何处理[错误和警告](https://code.visualstudio.com/docs/editor/editingevolved#_errors-warnings)。
## 生成本地预览版
1. 在 Linux 或 macOS `brew` 上使用安装该`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 备忘单
### 基本格式化
```
*bold text*
_italic text_
`monospace text`
```
### 标头
```
= Document Title (Header 1)
== Header 2
=== Header 3
==== Header 4
===== Header 5
====== Header 6
```
### Lists
未排序的列表：
```
- 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[]
```