Bagikan melalui

Praktik Terbaik Markdown

Artikel ini menyediakan panduan khusus untuk menggunakan Markdown dalam dokumentasi kami. Ini bukan tutorial untuk Markdown. Jika Anda memerlukan tutorial untuk Markdown, lihat cheatsheet Markdown ini.

Alur build yang membangun dokumentasi kami menggunakan markdig untuk memproses dokumen Markdown. Markdig mengurai dokumen berdasarkan aturan spesifikasi CommonMark terbaru. OPS mengikuti spesifikasi CommonMark dan menambahkan beberapa ekstensi untuk fitur khusus platform, seperti tabel dan pemberitahuan.

Spesifikasi CommonMark lebih ketat tentang konstruksi beberapa elemen Markdown. Perhatikan detail yang disediakan dalam dokumen ini.

Kami menggunakan ekstensi markdownlint di VISUAL Code untuk menerapkan aturan gaya dan pemformatan kami. Ekstensi ini diinstal sebagai bagian dari Learn Authoring Pack.

Baris, spasi, dan tab kosong

Baris kosong juga menandakan akhir blok di Markdown.

  • Kosongkan satu di antara blok Markdown dari berbagai jenis; misalnya, antara paragraf dan daftar atau header.
  • Jangan gunakan lebih dari satu baris kosong. Beberapa baris kosong dirender sebagai baris kosong tunggal dalam HTML, oleh karena itu baris kosong tambahan tidak perlu.
  • Jangan gunakan letakkan beberapa baris kosong berturut-turut dalam blok kode, baris kosong berturut-turut merusak blok kode.

Pengaturan spasi sangat penting dalam Markdown.

  • Hapus spasi tambahan di akhir baris. Spasi akhir dapat mengubah cara Markdown direnderkan.
  • Selalu gunakan spasi alih-alih tab (tab keras).

Judul dan tajuk

Gunakan judul ATX saja (# gaya, bukan gaya = atau -).

  • Gunakan huruf kalimat - hanya kata benda yang tepat dan huruf pertama judul atau header harus dikapitalisasi
  • Sertakan spasi tunggal antara # dan huruf pertama judul
  • Mengelilingi judul dengan baris kosong tunggal
  • Jangan gunakan lebih dari satu H1 per dokumen
    • Ini harus menjadi header pertama
    • Ini harus cocok dengan judul artikel
  • Naikkan tingkat header sebanyak satu - jangan lewati tingkat
  • Batasi kedalaman H3 atau H4
  • Hindari menggunakan markup tebal atau lainnya di header

Batasi panjang baris hingga 100 karakter

Untuk artikel konseptual dan referensi cmdlet, batasi baris hingga 100 karakter. Untuk about_ artikel, batasi panjang baris hingga 79 karakter. Membatasi panjang baris meningkatkan keterbacaan git diff dan riwayat. Ini juga memudahkan penulis lain untuk memberikan kontribusi.

Gunakan ekstensi Reflow Markdown di Visual Studio Code untuk me-reflow paragraf agar sesuai dengan panjang baris yang ditentukan.

Beberapa tipe konten tidak dapat dengan mudah dialirkan. Misalnya, kode di dalam blok kode juga dapat sulit untuk di-reflow, tergantung pada konten dan bahasa kode. Anda tidak dapat menata ulang tabel. Dalam kasus ini, gunakan penilaian terbaik Anda untuk menjaga konten sedekat mungkin dengan batas 100 karakter.

Penekanan

Untuk penekanan, Markdown mendukung huruf tebal dan huruf miring. Markdown memungkinkan Anda menggunakan salah satu dari * atau _ untuk menandai penekanan. Namun, agar konsisten dan menunjukkan niat:

  • Gunakan ** untuk tebal
  • Gunakan _ untuk miring

Mengikuti pola ini memudahkan orang lain untuk memahami niat markup ketika ada campuran tebal dan miring dalam dokumen.

Daftar

Jika daftar Anda memiliki beberapa kalimat atau paragraf, pertimbangkan untuk menggunakan subjudul daripada daftar.

Sisakan satu baris kosong di sekitar daftar.

Daftar yang tidak diurutkan

  • Jangan akhiri item daftar dengan titik kecuali berisi beberapa kalimat.
  • Gunakan karakter tanda hubung (-) untuk poin item daftar untuk menghindari kebingungan dengan markup penekanan yang menggunakan tanda bintang (*).
  • Untuk menyertakan paragraf atau elemen lain di bawah item poin peluru, sisipkan hentian baris dan sesuaikan indentasi dengan karakter pertama setelah poin peluru.

Contohnya:

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

Ini adalah daftar yang berisi sub-elemen di bawah bullet point.

  • Poin pertama

    Kalimat yang menjelaskan poin pertama.

    • Item poin anak

      Kalimat yang menjelaskan poin anak.

  • Butir kedua

  • Butir ketiga

Daftar yang diurutkan

  • Semua item dalam daftar bernomor harus menggunakan angka 1., bukan menambahkan angka pada setiap item.
    • Pemrosesan markdown menambah nilai secara otomatis.
    • Ini membuat menyusun ulang item lebih mudah dan menstandarkan indentasi konten subordinat.
  • Untuk menyertakan paragraf atau elemen lain di bawah item bernomor, ratakan indentasi dengan karakter pertama setelah nomor item.

Contohnya:

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

Markdown yang dihasilkan ditampilkan sebagai berikut:

  1. Untuk elemen pertama, masukkan spasi tunggal setelah 1. Kalimat panjang harus dipindahkan ke baris berikutnya dan harus sejajar dengan karakter pertama setelah penanda daftar bernomor.

    Untuk menyertakan elemen kedua, sisipkan jeda baris setelah yang pertama dan ratakan indentasi. Indentasi elemen kedua harus sejajar dengan posisi karakter pertama setelah penanda daftar bernomor.

  2. Item bernomor berikutnya dimulai di sini.

Gambar

Sintaks untuk menyertakan gambar adalah:

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

Di mana alt text adalah deskripsi singkat tentang gambar dan <folderPath> merupakan jalur relatif ke gambar.

  • Teks alternatif diperlukan untuk mendukung pembaca layar untuk gangguan visual.
  • Gambar harus disimpan dalam media/<article-name> folder dalam folder yang berisi artikel.
    • Buat folder yang namanya sesuai dengan file artikel Anda di dalam folder media. Salin gambar untuk artikel tersebut ke folder baru tersebut.
  • Jangan bagikan gambar antar artikel.
    • Jika gambar digunakan oleh beberapa artikel, setiap folder harus memiliki salinan gambar tersebut.
    • Ini mencegah perubahan pada gambar dalam satu artikel memengaruhi artikel lain.

Jenis file gambar berikut didukung: *.png, , *.gif, *.jpeg, *.jpg, *.svg

Ekstensi markdown - Kotak pemberitahuan

Learn Authoring Pack berisi alat yang mendukung fitur unik untuk sistem penerbitan kami. Pemberitahuan adalah ekstensi Markdown untuk membuat blockquotes yang dirender dengan warna dan ikon yang menyoroti signifikansi konten. Jenis pemberitahuan berikut ini didukung:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Pemberitahuan ini terlihat seperti ini di Microsoft Learn:

Blok Catatan

Nota

Informasi yang harus diperhatikan pengguna bahkan jika membaca sekilas.

Blok tip

Petunjuk / Saran

Informasi opsional untuk membantu pengguna menjadi lebih sukses.

Blok penting

Penting

Informasi penting yang diperlukan untuk keberhasilan pengguna.

Blok peringatan

Perhatian

Konsekuensi potensial negatif dari suatu tindakan.

Blok peringatan

Peringatan

Konsekuensi tertentu yang berbahaya dari suatu tindakan.

Ekstensi Markdown - Tabel

Tabel adalah susunan data dengan baris dan kolom yang terdiri dari:

  • Satu baris judul
  • Baris pemisah yang memisahkan header dari data
  • Baris data nol atau lebih

Setiap baris terdiri dari sel yang berisi teks arbitrer yang dipisahkan oleh pipa (|). Pipa terkemuka dan di belakang juga direkomendasikan untuk kejelasan. Spasi antara pipa dan konten sel dipangkas. Elemen tingkat blok tidak dapat disisipkan dalam tabel. Semua konten baris harus berada pada satu baris.

Baris pemisah terdiri dari sel yang hanya berisi tanda hubung (-), dan secara opsional, titik dua di awal atau akhir (:), atau keduanya, untuk menunjukkan perataan kiri, kanan, atau tengah.

Untuk tabel kecil, pertimbangkan untuk menggunakan daftar sebagai gantinya. Daftarnya adalah:

  • Lebih mudah dirawat dan dibaca
  • Dapat disusun ulang agar sesuai dengan batas garis 100 karakter
  • Lebih mudah diakses bagi pengguna yang menggunakan pembaca layar untuk bantuan visual

Untuk informasi selengkapnya, lihat bagian Tabeldari referensi Markdown untuk Microsoft Learn.

  • Hyperlink harus menggunakan sintaks [friendlyname](url-or-path)Markdown .

  • Sistem penerbitan mendukung tiga jenis tautan:

    • Tautan URL
    • Tautan file
    • Tautan referensi silang

  • Semua URL ke situs web eksternal harus menggunakan HTTPS kecuali tidak valid untuk situs target.

  • Tautan harus memiliki nama yang mudah diingat, biasanya judul artikel yang ditautkan

  • Hindari menggunakan backtick, tebal, atau markup lain di dalam tanda kurung hyperlink.

  • URL mentah dapat digunakan saat Anda mendokumentasikan URI tertentu tetapi harus diapit dalam tanda backtick. Contohnya:

    By default, if you don't specify this parameter, the DMTF standard resource URI
`http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.

  • Gunakan referensi tautan jika diizinkan. Referensi tautan dalam paragraf membuat paragraf lebih mudah dibaca.

    Referensi tautan membagi tautan Markdown menjadi dua bagian:

    • referensi tautan - [friendlyname][id]
    • definisi dari tautan - [id]: url-or-path
  • Tautan URL ke artikel lain di learn.microsoft.com harus menggunakan jalur relatif situs. Cara paling sederhana untuk membuat tautan relatif situs adalah dengan menyalin URL dari browser Anda lalu menghapus https://learn.microsoft.com/en-us dari nilai yang Anda tempelkan ke markdown.
  • Jangan sertakan lokal dalam URL di properti Microsoft (hapus /en-us dari URL) atau tautan Wikipedia.
  • Hapus parameter kueri yang tidak perlu dari URL. Contoh yang harus dihapus:
    • ?view=powershell-5.1 - digunakan untuk menautkan ke versi PowerShell tertentu
    • ?redirectedfrom=MSDN - ditambahkan ke URL saat Anda dialihkan dari artikel lama ke lokasi barunya
  • Jika Anda perlu menautkan ke versi dokumen tertentu, Anda harus menambahkan &preserve-view=true parameter ke string kueri. Misalnya: ?view=powershell-5.1&preserve-view=true
  • Di situs Microsoft, tautan URL tidak berisi ekstensi file (misalnya, tidak ada .md)
  • Tautan file digunakan untuk menautkan dari satu artikel referensi ke artikel lain, atau dari satu artikel konseptual ke artikel lainnya dalam docset yang sama.
    • Jika Anda perlu menautkan dari artikel konseptual ke artikel referensi, Anda harus menggunakan tautan URL.
    • Jika Anda perlu menautkan ke artikel di docset lain atau di seluruh repositori, Anda harus menggunakan tautan URL.
  • Gunakan filepath relatif (misalnya: ../folder/file.md)
  • Semua jalur file menggunakan karakter garis miring (/)
  • Sertakan ekstensi file (misalnya, .md)

Tautan referensi silang adalah fitur khusus yang didukung oleh sistem penerbitan. Anda dapat menggunakan tautan referensi silang dalam artikel konseptual untuk menautkan ke .NET API atau referensi cmdlet.

  • Untuk tautan ke referensi .NET API, lihat Menggunakan tautan dalam dokumentasi di Panduan Kontributor pusat.

  • Tautan ke referensi cmdlet memiliki format berikut: xref:<module-name>.<cmdlet-name>. Misalnya, untuk menautkan Get-Content ke cmdlet dalam modul Microsoft.PowerShell.Management .

    [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

Penghubungan Mendalam

Penautan mendalam diizinkan pada URL dan tautan file.

  • Teks jangkar harus huruf kecil
  • Tambahkan jangkar ke akhir jalur target. Misalnya:
    • [about_Splatting](about_Splatting.md#splatting-with-arrays)
    • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

Untuk informasi selengkapnya, lihat Menggunakan tautan dalam dokumentasi.

Rentang kode

Rentang kode digunakan untuk cuplikan kode sebaris dalam paragraf. Gunakan tanda backtick tunggal untuk menunjukkan rentang kode. Contohnya:

PowerShell cmdlet names use the `Verb-Noun` naming convention.

Contoh ini ditampilkan sebagai:

Nama cmdlet PowerShell menggunakan Verb-Noun konvensi penamaan.

Blok kode

Blok kode digunakan untuk contoh perintah, sampel kode multibaris, bahasa kueri, dan output. Dua cara untuk menunjukkan bagian teks dalam file artikel sebagai blok kode adalah dengan mengapitnya menggunakan triple-backtick (```) atau dengan mengindentasinya.

Jangan pernah menggunakan indentasi karena terlalu mudah untuk salah dan mungkin sulit bagi penulis lain untuk memahami niat Anda ketika mereka perlu mengedit artikel Anda.

Blok kode bergaris dapat menyertakan tag opsional yang menunjukkan sintaks bahasa yang terkandung dalam blok. Platform penerbitan mendukung daftar tag bahasa. Tag bahasa digunakan untuk memberikan penyorotan sintaksis saat artikel dirender di halaman web. Tag bahasa tidak peka huruf besar/kecil, tetapi Anda sebaiknya menggunakan huruf kecil kecuali dalam beberapa kasus khusus.

  • Pagar kode tanpa tag dapat digunakan untuk blok sintaksis atau jenis konten lain di mana penyorotan sintaks tidak diperlukan.
  • Saat menampilkan output dari perintah, gunakan pagar kode yang sudah ditandai dengan tag bahasa Output. Kotak yang dirender diberi label sebagai Output dan tidak memiliki penyorotan sintaks.
  • Jika output dalam bahasa tertentu yang didukung, gunakan tag bahasa yang sesuai. Misalnya, banyak perintah menghasilkan JSON, jadi gunakan json tag .
  • Jika Anda menggunakan tag bahasa yang tidak didukung, blok kode akan dirender tanpa penyorotan sintaks. Tag bahasa menjadi label untuk kotak kode yang dirender di halaman web. Gunakan huruf kapital pada tag sehingga label tampil dengan huruf kapital di halaman web.

Langkah berikutnya

panduan gaya PowerShell

  • Last updated on