既存の寄稿者の概要ローカル編集環境のセットアップ github.dev ウェブベースのエディタを使用する 1 ページの編集ページの ID を表示および設定する新しいページを作成するイメージを挿入する Vale でスタイルを確認するローカルプレビューを構築する AsciiDoc チートシート

このガイドへの貢献

誰でもベストプラクティスガイドに貢献できます。EKS ベストプラクティスガイドは、GitHub の AsciiDoc 形式で書かれています。

既存の寄稿者の概要

VS Code bpg-docs.code-workspaceでを開き、AsciiDoc 拡張機能を自動的にインストールします。
- Visual Studio Marketplace の AsciiDoc 拡張機能の詳細をご覧ください。
AWS Docs ウェブサイトのソースファイルはに保存されます。 latest/bpg
構文はマークダウンとよく似ています。
- AsciiDoctor ドキュメントの構文リファレンスを確認します。
docs プラットフォームはのみをデプロイしますlatest/bpg/images。各ガイドセクションには、このディレクトリへのシンボリックリンクがあります。たとえば、はをlatest/bpg/networking/images指していますlatest/bpg/images。

ローカル編集環境のセットアップ

ガイドを頻繁に編集する場合は、ローカル編集環境を設定します。

リポジトリをフォークしてクローンする

git、github、およびテキストエディタに精通している必要があります。git およびの開始方法についてはgithub、GitHub ドキュメントの「GitHub アカウントの開始方法」を参照してください。 GitHub

GitHub で EKS ベストプラクティスガイドを参照してください。
プロジェクトリポジトリのフォークを作成します。GitHub ドキュメントでリポジトリをフォークする方法について説明します。
プロジェクトリポジトリのフォークをクローンします。分岐リポジトリのクローンを作成する方法について説明します。

VS Code Workspace を開く

AWS では、Microsoft の Visual Studio Code を使用してガイドを編集することをお勧めします。VS Code の詳細については、Visual Studio Code ドキュメントの「Visual Studio Code のダウンロード」および「Visual Studio Code の開始方法」を参照してください。

VS Code を開きます。
クローンされたリポジトリから 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 ウェブベースのエディタを使用する

github.dev ウェブベースのエディタは VS Code に基づいています。これは、セットアップなしで複数のファイルを編集し、コンテンツをプレビューする優れた方法です。

AsciiDoc 拡張機能がサポートされています。GUI を使用して git オペレーションを実行できます。ウェブベースのエディタには、コマンドを実行するためのシェルやターミナルはありません。

GitHub アカウントが必要です。必要に応じてログインするように求められます。

🚀 GitHub ウェブベースのエディタを起動します。

1 ページの編集

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]
```
を新しいページのページ ID my-new-pageに置き換えます。
ファイルを保存します。

注記

ページ IDsは、ドキュメントサイト全体で一意である必要があります。既存のページ ID を使用しようとすると、ビルドエラーが発生します。

新しいページを作成する

新しいページを作成し、ガイドの目次を更新する方法について説明します。

ページメタデータを作成する

ページタイトルとページショートタイトルを決定します。ページの短いタイトルはオプションですが、ページのタイトルが数語を超える場合は推奨されます。
ページの ID を決定します。これは、EKS ベストプラクティスガイド内で一意である必要があります。規則では、すべての小文字を使用し、で単語を区切ります-。
必要に応じてフォルダに新しい asciidoc ファイルを作成し、次のテキストをファイルに追加します。

例
[."topic"] [#<page-id>] = <page-title> :info_titleabbrev: <page-short-title>

例えば、

例
[."topic"] [#scalability] = EKS Scalability のベストプラクティス :info_titleabbrev: Scalability

目次に追加する

目次で親ページのファイルを開きます。新しい最上位ガイドセクションの場合、親ファイルはですbook.adoc。
親ファイルの下部で、次のディレクティブを更新して挿入します。

例
include::<new-filename>[leveloffset=+1]

例えば、

例
include::dataplane.adoc[leveloffset=+1]

イメージを挿入する

編集するページのイメージプレフィックスを見つけます。ファイルの見出しの :imagesdir:プロパティを確認します。例については、 `:imagesdir: images/reliability/
イメージを次のようにこのパスに配置します。 latest/bpg/images/reliability
イメージに適した alt-text を決定します。イメージの簡単な概要を記述します。たとえば、「3 つのアベイラビリティーゾーンを持つ VPC のダイアグラム」は適切な alt-text です。
次の例を alt-text とイメージファイル名で更新します。目的の場所にを挿入します。

例
image::<image-filename>[<image-alt-text>]

例えば、

例
image::eks-data-plane-connectivity.jpeg[ネットワーク図]

Vale でスタイルを確認する

Vale CLI をインストールします。
vale sync を実行する
Visual Studio Marketplace から Vale Extension をインストールします。
VS Code を再起動し、AsciiDoc ファイルを開きます。
VS Code は問題のあるテキストを強調します。VS Code ドキュメントでエラーと警告を使用する方法について説明します。

ローカルプレビューを構築する

Linux または MacOS brew でを使用してasciidoctorツールをインストールする
- AsciiDoctor ドキュメントで asciidoctor CLI をインストールする方法について説明します。 AsciiDoctor
- brew パッケージマネージャーをインストールする方法について説明します。
ターミナルを開き、に移動します。 latest/bpg/
asciidoctor book.adoc を実行する
- 構文の警告とエラーを確認する
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

Links


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[]

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

パフォーマンス