为本指南做出贡献 - Amazon EKS
现有贡献者摘要设置本地编辑环境使用 github.dev 基于网络的编辑器编辑单个页面查看和设置页面的 ID创建新页面插入图片向淡水河谷查询风格生成本地预览版AsciiDoc 备忘单

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

为本指南做出贡献

任何人都可以为最佳实践指南做出贡献。《EKS 最佳实践指南》的 AsciiDoc 格式为 GitHub。

现有贡献者摘要

  • bpg-docs.code-workspace使用 VS Code 打开，即可自动安装 AsciiDoc 扩展程序。

    • 在 Visual Studio Marketplace 上了解有关AsciiDoc 扩展的更多信息。

  • AWS Docs 网站的源文件存储在 latest/bpg

  • 其语法与 markdown 非常相似。

  • 仅部署latest/bpg/images文档平台。每个指南章节都有一个指向该目录的符号链接。例如，latest/bpg/networking/images指向latest/bpg/images。

设置本地编辑环境

如果您计划经常编辑指南，请设置本地编辑环境。

分叉并克隆存储库

您需要熟悉gitgithub、和文本编辑器。有关git和入门的信息github，请参阅 GitHub 文档中的 GitHub 账户入门。

  1. 在上查看 EKS 最佳实践指南 GitHub。

  2. 创建项目存储库的分支。在 GitHub 文档中学习如何分叉存储库。

  3. 克隆您的项目仓库分支。了解如何克隆您的分叉存储库。

打开 VS 代码工作区

AWS 建议使用微软提供的 Visual Studio 代码来编辑该指南。有关 VS Code 的更多信息，请参阅 V isual Studio 代码文档中的下载 V isual Studio 代码和开始使用 Visual Studio 代码。

  1. 打开 VS Code。

  2. 从克隆的存储库中打开bpg-docs.code-workspace文件。

  3. 如果这是您第一次打开此工作区，请接受安装 AsciiDoc 扩展程序的提示。此扩展程序会检查 AsciiDoc 文件的语法并生成实时预览。

  4. 浏览到该latest/bpg目录。此目录包含部署到 AWS 文档站点的源文件。源文件按指南部分进行组织，例如 “安全” 或 “网络”。

编辑文件

  1. 在编辑器中打开一个文件。

    • 查看 AsciiDoc 语法以了解如何创建标题、链接和列表。

    • 您可以使用 Markdown 语法来设置文本格式、创建列表和标题。你不能使用 Markdown 语法来创建链接。

  2. 打开页面的实时预览。

    • 首先，按ctrl-k或cmd-k（视键盘而定）。其次，按v。这将在分屏视图中打开预览。

AWS 建议使用功能分支来组织您的更改。学习如何使用 git 创建分支。

提交拉取请求

您可以从 GitHub 网站或 GitHub cli 创建拉取请求。

了解如何使用 GitHub 网站从 fork 创建拉取请求。

了解如何使用 GitHub cli 创建拉取请求。

使用 github.dev 基于网络的编辑器

github.dev基于 Web 的编辑器基于 VS Code。这是无需任何设置即可编辑多个文件和预览内容的好方法。

它支持该 AsciiDoc 扩展。你可以使用 GUI 进行 git 操作。基于 Web 的编辑器没有用于运行命令的 shell 或终端。

你必须有一个 GitHub 账户。如果需要，系统将提示您登录。

🚀 启动 GitHub 基于 Web 的编辑器。

编辑单个页面

您可以使用快速更新各个页面 GitHub。每个页面的底部都包含一个 “📝 在 GitHub” 上编辑此页面” 链接。

  1. 导航到本指南中您要编辑的页面

  2. 点击底部的 “编辑此页面 GitHub” 链接

  3. 单击 GitHub 文件查看器右上角的编辑铅笔图标，或按 e

  4. 编辑文件

  5. 使用 “提交更改...” 按钮提交您的更改。此按钮可创建 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. 在文本编辑器中打开新页面的源文件。

  2. 在文件顶部，添加以下行。它应该在第一个标题之上。

    [#my-new-page]

    my-new-page替换为新页面的页面 ID。

  3. 保存该文件。

注意

在整个文档网站中，页面 IDs 必须是唯一的。如果您尝试使用现有的页面 ID，则会收到构建错误。

创建新页面

了解如何创建新页面和更新指南目录。

创建页面元数据

  1. 确定页面标题和页面简称。页面短标题是可选的，但如果页面标题超过几个字，则建议使用该标题。

  2. 确定页面的 ID。这在《EKS 最佳实践指南》中必须是唯一的。惯例是全部使用小写字母，并使用-分隔单词。

  3. 如果需要，在文件夹中创建一个新的 asciidoc 文件，然后向该文件中添加以下文本：

    [。” 主题 "] [#<page-id>] =<page-title>: info_titleabbrev: < > page-short-title

    例如，

    [。” 主题 "] [#scalability] = EKS 可扩展性最佳实践：info_titleabbrev：可扩展性

添加到目录

  1. 在目录中打开父页面的文件。对于新的顶级指南章节，父文件为book.adoc。

  2. 在父文件的底部，更新并插入以下指令：

    包括:: <new-filename>[leveloffset=+1]

    例如，

    包括:: dataplane.adoc [leveloffset=+1]

插入图片

  1. 查找您正在编辑的页面的图像前缀。查看文件标题中的:imagesdir:属性。举个例子，`:imagesdir: images/reliability/

  2. 将您的图片放在此路径中，例如 latest/bpg/images/reliability

  3. 为您的图片确定合适的替代文本。为图像写一个简短的高级描述。例如，“具有三个可用区的 VPC 示意图” 是恰当的替代文本。

  4. 使用替代文本和图像文件名更新以下示例。在所需位置插入。

    图片:: <image-filename>[< image-alt-text >]

    例如，

    图片:: eks-data-plane-connectivity .jpeg [网络图]

向淡水河谷查询风格

  1. 安装 Vale CLI。

  2. 运行 vale sync

  3. 从 Visual Studio Marketplace 安装谷扩展程序。

  4. 重启 VS Code，然后打开一个 AsciiDoc 文件

  5. VS Code 在有问题的文本下划线。在 VS Code 文档中学习如何处理错误和警告。

生成本地预览版

  1. 在 Linux 或 macOS brew 上使用安装该asciidoctor工具

  2. 打开终端，然后导航至 latest/bpg/

  3. 运行 asciidoctor book.adoc

    • 查看所有语法警告和错误

  4. 打开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: <<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[]