翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # このガイドへの貢献 誰でもベストプラクティスガイドに貢献できます。EKS ベストプラクティスガイドは、GitHub の AsciiDoc 形式で書かれています。 ## 既存の寄稿者の概要 + VS Code [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)で を開き、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) + 構文はマークダウンとよく似ています。 + AsciiDoctor ドキュメントの[構文リファレンス](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/)を確認します。 + docs プラットフォームは のみをデプロイします`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)する方法について説明します。 1. プロジェクトリポジトリのフォークをクローンします。[分岐リポジトリのクローンを作成する](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository)方法について説明します。 ### VS Code Workspace を開く AWS では、Microsoft の Visual Studio Code を使用してガイドを編集することをお勧めします。VS Code の詳細については、[Visual Studio Code ドキュメントの「Visual Studio Code のダウンロード](https://code.visualstudio.com/download)[」および「Visual Studio Code の開始方法](https://code.visualstudio.com/docs/getstarted/getting-started)」を参照してください。 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 ウェブベースのエディタを使用する `github.dev` ウェブベースのエディタは VS Code に基づいています。これは、セットアップなしで複数のファイルを編集し、コンテンツをプレビューする優れた方法です。 AsciiDoc 拡張機能がサポートされています。GUI を使用して git オペレーションを実行できます。ウェブベースのエディタには、コマンドを実行するためのシェルやターミナルはありません。 GitHub アカウントが必要です。必要に応じてログインするように求められます。 [🚀 GitHub ウェブベースのエディタを起動します。](https://github.dev/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace?workspace=true) ## 1 ページの編集 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] ``` を新しいページのページ ID `my-new-page`に置き換えます。 1. ファイルを保存します。 **注記** ページ IDsは、ドキュメントサイト全体で一意である必要があります。既存のページ ID を使用しようとすると、ビルドエラーが発生します。 ## 新しいページを作成する 新しいページを作成し、ガイドの目次を更新する方法について説明します。 ### ページメタデータを作成する 1. ページタイトルとページショートタイトルを決定します。ページの短いタイトルはオプションですが、ページのタイトルが数語を超える場合は推奨されます。 1. ページの ID を決定します。これは、EKS ベストプラクティスガイド内で一意である必要があります。規則では、すべての小文字を使用し、 で単語を区切ります`-`。 1. 必要に応じてフォルダに新しい asciidoc ファイルを作成し、次のテキストをファイルに追加します。 **Example** [."topic"] [\$1] = :info\$1titleabbrev: 例えば、 **Example** [."topic"] [\$1scalability] = EKS Scalability のベストプラクティス :info\$1titleabbrev: Scalability ### 目次に追加する 1. 目次で親ページの ファイルを開きます。新しい最上位ガイドセクションの場合、親ファイルは です`book.adoc`。 1. 親ファイルの下部で、次のディレクティブを更新して挿入します。 **Example** include::[leveloffset=\$11] 例えば、 **Example** include::dataplane.adoc[leveloffset=\$11] ## イメージを挿入する 1. 編集するページのイメージプレフィックスを見つけます。ファイルの見出しの `:imagesdir:`プロパティを確認します。例については、 ``:imagesdir: images/reliability/` 1. イメージを次のようにこのパスに配置します。 `latest/bpg/images/reliability` 1. イメージに適した alt-text を決定します。イメージの簡単な概要を記述します。たとえば、「3 つのアベイラビリティーゾーンを持つ 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 Extension](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 ドキュメントで 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 ``` ### Links ``` 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[] ```