Berkontribusi pada panduan ini

Siapa pun dapat berkontribusi pada panduan praktik terbaik. Panduan Praktik Terbaik EKS ditulis dalam AsciiDoc format pada GitHub.

Ringkasan untuk kontributor yang ada

• Buka bpg-docs.code-workspacedengan VS Code untuk menginstal AsciiDoc ekstensi secara otomatis.

  • Pelajari lebih lanjut tentang AsciiDoc Ekstensi di Marketplace Visual Studio.

• File sumber untuk situs web AWS Docs disimpan di latest/bpg

• Sintaksnya sangat mirip dengan penurunan harga.

  • Tinjau Referensi Sintaks di AsciiDoctor dokumen.

• Platform dokumen hanya menerapkanlatest/bpg/images. Setiap bagian panduan memiliki tautan simbolis kembali ke direktori ini. Misalnya, latest/bpg/networking/images menunjuk kelatest/bpg/images.

Siapkan lingkungan pengeditan lokal

Jika Anda berencana untuk sering mengedit panduan, siapkan lingkungan pengeditan lokal.

Garpu dan kloning repo

Anda harus terbiasa dengangit,github, dan editor teks. Untuk informasi tentang memulai git dangithub, lihat Memulai GitHub akun Anda di GitHub dokumen.

1. Lihat Panduan Praktik Terbaik EKS di GitHub.

2. Buat fork dari repo proyek. Pelajari cara melakukan fork repositori di dokumen. GitHub

3. Kloning garpu repo proyek Anda. Pelajari cara mengkloning repositori bercabang Anda.

Buka Ruang Kerja VS Code

AWS merekomendasikan penggunaan Visual Studio Code dari Microsoft untuk mengedit panduan. Untuk informasi selengkapnya tentang VS Code, lihat Download Visual Studio Code dan Memulai Visual Studio Code di Visual Studio Code Documentation.

1. Buka Kode VS.

2. Buka bpg-docs.code-workspace file dari repo kloning.

3. Jika ini adalah pertama kalinya Anda membuka ruang kerja ini, terima prompt untuk menginstal AsciiDoc ekstensi. Ekstensi ini memeriksa sintaks AsciiDoc file dan menghasilkan pratinjau langsung.

4. Jelajahi ke latest/bpg direktori. Direktori ini menyimpan file sumber yang diterapkan ke situs dokumentasi AWS. File sumber diatur oleh bagian panduan, seperti “keamanan” atau “jaringan”.

Mengedit file

1. Buka file di editor.

   • Lihat AsciiDoc Sintaks untuk mempelajari cara membuat judul, tautan, dan daftar.

   • Anda dapat menggunakan sintaks Markdown untuk memformat teks, membuat daftar, dan judul. Anda tidak dapat menggunakan sintaks Markdown untuk membuat tautan.

2. Buka pratinjau langsung halaman.

   • Pertama, tekan ctrl-k atau cmd-k (tergantung keyboard). Kedua, tekanv. Ini membuka pratinjau dalam tampilan terpisah.

AWS menyarankan untuk menggunakan cabang fitur untuk mengatur perubahan Anda. Pelajari cara membuat cabang dengan git.

Kirim Permintaan Tarik

Anda dapat membuat permintaan tarik dari GitHub situs web atau GitHub cli.

Pelajari cara membuat permintaan tarik dari garpu dengan menggunakan GitHub Situs Web.

Pelajari cara membuat permintaan tarik dengan menggunakan GitHub cli.

Gunakan editor berbasis web github.dev

Editor github.dev berbasis web didasarkan pada VS Code. Ini adalah cara yang bagus untuk mengedit banyak file dan mempratinjau konten tanpa pengaturan apa pun.

Ini memiliki dukungan untuk AsciiDoc ekstensi. Anda dapat melakukan operasi git dengan menggunakan GUI. Editor berbasis web tidak memiliki shell atau terminal untuk menjalankan perintah.

Anda harus memiliki GitHub akun. Anda akan diminta untuk login jika diperlukan.

🚀 Luncurkan editor GitHub berbasis web.

Mengedit satu halaman

Anda dapat dengan cepat memperbarui halaman individual dengan menggunakan GitHub. Setiap halaman berisi tautan "📝 Edit halaman ini di GitHub" di bagian bawah.

1. Arahkan ke halaman dalam panduan ini yang ingin Anda edit

2. Klik tautan “Edit halaman ini di GitHub” di bagian bawah

3. Klik ikon edit pensil di kanan atas penampil GitHub file, atau tekan e

4. Edit file

5. Kirim perubahan Anda menggunakan tombol “Komit perubahan...”. Tombol ini membuat permintaan GitHub tarik. Pengelola panduan akan meninjau permintaan tarik ini. Peninjau akan menyetujui permintaan tarik, atau meminta perubahan.

Melihat dan mengatur ID untuk halaman

Halaman ini menjelaskan cara melihat dan mengatur ID halaman.

ID halaman adalah string unik yang mengidentifikasi setiap halaman di situs dokumentasi. Anda dapat melihat ID halaman di bilah alamat browser Anda saat Anda berada di halaman tertentu. ID halaman digunakan untuk URL, nama file, dan untuk membuat tautan referensi silang.

Misalnya, jika Anda melihat halaman ini, URL di bilah alamat browser Anda akan terlihat mirip dengan:

https://docs.aws.amazon.com/view-set-page-id.html

Bagian terakhir dari URL (view-set-page-id) adalah ID halaman.

Mengatur ID halaman

Saat membuat halaman baru, Anda perlu mengatur ID halaman di file sumber. ID halaman harus berupa string ringkas dan tanda hubung yang menjelaskan konten halaman.

1. Buka file sumber untuk halaman baru Anda di editor teks.

2. Di bagian atas file, tambahkan baris berikut. Itu harus di atas judul pertama.

   [#my-new-page]

   Ganti my-new-page dengan ID halaman untuk halaman baru Anda.

3. Simpan file tersebut.

catatan

Halaman IDs harus unik di seluruh situs dokumentasi. Jika Anda mencoba menggunakan ID halaman yang ada, Anda akan mendapatkan error build.

Buat halaman baru

Pelajari cara membuat halaman baru dan memperbarui daftar isi panduan.

Buat metadata halaman

1. Tentukan judul halaman, dan judul pendek halaman. Judul pendek halaman adalah opsional, tetapi disarankan jika judul halaman lebih dari beberapa kata.

2. Tentukan ID halaman. Ini harus unik dalam Panduan Praktik Terbaik EKS. Konvensi adalah menggunakan semua huruf kecil, dan memisahkan kata-kata dengan. -

3. Buat file asciidoc baru, dalam folder jika diperlukan, dan tambahkan teks berikut ke file:

   [.” topik "] [#<page-id>] = <page-title>:info_titleabbrev: < > page-short-title

   Misalnya,

   [.” topik "] [#scalability] = Praktik terbaik skalabilitas EKS:info_titleabbrev: Skalabilitas

Tambahkan ke daftar isi

1. Buka file untuk halaman induk dalam daftar isi. Untuk bagian panduan tingkat atas yang baru, file induknya adalahbook.adoc.

2. Di bagian bawah file induk, perbarui dan masukkan arahan berikut:

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

   Sebagai contoh,

   termasuk: :dataplane.adoc [leveloffset = +1]

Menyisipkan gambar

1. Temukan awalan gambar untuk halaman yang Anda edit. Tinjau :imagesdir: properti di judul file. Sebagai contoh, `:imagesdir: images/reliability/

2. Tempatkan gambar Anda di jalur ini, seperti latest/bpg/images/reliability

3. Tentukan alt-text yang sesuai untuk gambar Anda. Tulis deskripsi singkat tingkat tinggi dari gambar. Misalnya, “diagram VPC dengan tiga zona ketersediaan” adalah teks alt yang sesuai.

4. Perbarui contoh berikut dengan alt-text dan nama file gambar. Masukkan di lokasi yang diinginkan.

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

   Misalnya,

   gambar:: eks-data-plane-connectivity .jpeg [Diagram jaringan]

Periksa gaya dengan Vale

1. Instal CLI Vale.

2. Jalankan vale sync

3. Instal Vale Extension dari Visual Studio Marketplace.

4. Mulai ulang VS Code, dan buka AsciiDoc file

5. VS Code menggarisbawahi teks bermasalah. Pelajari cara bekerja dengan Kesalahan dan Peringatan di dokumen VS Code.

Membangun pratinjau lokal

1. Instal asciidoctor alat menggunakan brew di Linux atau macOS

   • Pelajari cara menginstal asciidoctor cli di dokumen. AsciiDoctor

   • Pelajari caranya instal manajer paket brew.

2. Buka terminal, dan arahkan ke latest/bpg/

3. Jalankan asciidoctor book.adoc

   • Tinjau peringatan dan kesalahan sintaks apa pun

4. Buka file book.html output.

   • Di macOS, Anda dapat menjalankan open book.html untuk membuka pratinjau di browser default Anda.

AsciiDoc Lembar Cheat

Pemformatan Dasar

*bold text*
_italic text_
`monospace text`

Header

= Document Title (Header 1)
== Header 2
=== Header 3
==== Header 4
===== Header 5
====== Header 6

Daftar

Daftar Tidak Berurutan:

- Item 1
- Item 2
-- Subitem 2.1
-- Subitem 2.2
- Item 3

Daftar yang Dipesan:

. First item
. Second item
.. Subitem 2.1
.. Subitem 2.2
. Third item

Tautan

External link:  https://example.com[Link text]
Internal link: <<page-id>>
Internal link: xref:page-id[Link text]

Citra

image::image-file.jpg[Alt text]

Blok Kode

 [source,python]
 ----
 def hello_world():
     print("Hello, World!")
 ----

Tabel

Pelajari cara membuat tabel dasar.

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

Peringatan

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.

Pratinjau:

catatan

Ini adalah peringatan catatan.

Penyertaan

 include::filename.adoc[]