CommonMark: Spesifikasi Formal Untuk Penurunan Harga

CommonMark adalah versi sintaks Markdown yang dirasionalisasi dengan spesifikasi yang tujuannya adalah untuk menghilangkan ambiguitas dan inkonsistensi seputar spesifikasi Markdown asli. Ini menawarkan spesifikasi standar yang mendefinisikan sintaks umum bahasa bersama dengan serangkaian tes komprehensif untuk memvalidasi implementasi penurunan harga terhadap spesifikasi ini.

GitHub menggunakan Markdown sebagai bahasa markup untuk konten penggunanya.

“CommonMark adalah proyek ambisius untuk secara formal menentukan sintaks Markdown yang digunakan oleh banyak situs web di internet dengan cara yang mencerminkan penggunaannya di dunia nyata [...] Hal ini memungkinkan orang untuk terus menggunakan Markdown dengan cara yang sama seperti yang selalu mereka lakukan sambil menawarkan pengembang spesifikasi yang komprehensif dan implementasi referensi untuk beroperasi dan menampilkan penurunan harga secara konsisten antar platform.”

— “Spesifikasi Formal Untuk Penurunan Harga GitHub,” Blog GitHub

Pada tahun 2012, GitHub mulai menciptakan rasa Markdown sendiri — GitHub Flavoured Markdown (GFM) — untuk memerangi kurangnya standarisasi Markdown, dan memperluas sintaks sesuai kebutuhannya. GFM dibangun di atas Sundown, sebuah parser yang khusus dibangun oleh GitHub untuk mengatasi beberapa kekurangan dari parser Markdown yang ada saat itu. Lima tahun kemudian, pada tahun 2017, ia mengumumkan penghentian Sundown yang mendukung perpustakaan penguraian dan rendering CommonMark, cmark dalam spesifikasi formal untuk GitHub Flavoured Markdown.

Di bagian Pertanyaan Umum dari Penurunan Harga dan Kode Visual Studio, didokumentasikan bahwa Penurunan Harga di VSCode menargetkan spesifikasi Penurunan Harga CommonMark menggunakan perpustakaan penurunan harga, yang dengan sendirinya mengikuti spesifikasi CommonMark.

CommonMark telah diadopsi dan diimplementasikan secara luas (lihat Daftar Implementasi CommonMark) untuk digunakan dalam bahasa yang berbeda seperti C (misalnya cmark), C# (misalnya CommonMark.NET), JavaScript (misalnya markdown-it) dll. Ini adalah kabar baik sebagai pengembang dan penulis secara bertahap pindah ke batas baru untuk dapat menggunakan penurunan harga dengan sintaks yang konsisten, dan spesifikasi standar.

Catatan Singkat Tentang Pengurai Penurunan Harga

Pengurai penurunan harga adalah inti dari mengubah teks penurunan harga menjadi HTML, secara langsung atau tidak langsung.

Parser seperti cmark dan commonmark.js tidak mengonversi Markdown ke HTML secara langsung, melainkan mengubahnya menjadi Pohon Sintaks Abstrak (AST), dan kemudian membuat AST sebagai HTML, membuat prosesnya lebih terperinci dan dapat dimanipulasi. Di antara penguraian — ke AST — dan rendering — ke HTML — misalnya, teks penurunan harga dapat diperpanjang.

Dukungan Sintaks Penurunan Harga CommonMark

Proyek atau platform yang telah menerapkan spesifikasi CommonMark sebagai dasar dari cita rasa spesifiknya sering kali merupakan superset dari subset ketat spesifikasi CommonMark Markdown. Untuk sebagian besar, CommonMark telah mengurangi banyak ambiguitas dengan membangun spesifikasi yang dibangun untuk dibangun. GFM adalah contoh utama, meskipun mendukung setiap sintaks CommonMark, GFM juga memperluasnya agar sesuai dengan penggunaannya.

Dukungan sintaks CommonMark dapat dibatasi pada awalnya, misalnya, ia tidak memiliki dukungan untuk sintaks tabel ini, tetapi penting untuk mengetahui bahwa ini adalah desain karena komentar di utas percakapan ini mengungkapkan: bahwa sintaks yang didukung ketat dan dikatakan menjadi sintaks inti dari bahasa itu sendiri — sama yang ditentukan oleh penciptanya, John Gruber dalam Markdown: Syntax.

Pada saat penulisan, berikut adalah sejumlah sintaks yang didukung:

1. Paragraf dan Hentian Baris,
2. header,
3. Penekanan dan Penekanan Kuat,
4. Aturan Horisontal,
5. Daftar,
6. Tautan,
7. Gambar-gambar,
8. kutipan blok,
9. Kode,
10. Blok Kode.

Untuk mengikuti contoh, disarankan agar Anda menggunakan editor dingus commonmark.js untuk mencoba sintaks dan mendapatkan Pratinjau yang dirender, HTML yang dihasilkan, dan AST.

Paragraf dan Pemisahan Baris

Di Markdown, paragraf adalah baris teks yang berkesinambungan yang dipisahkan oleh setidaknya satu baris kosong.

Aturan berikut menentukan paragraf:

1. Paragraf penurunan harga dirender dalam HTML sebagai elemen Paragraf, <p>.
2. Paragraf yang berbeda dipisahkan dengan satu atau lebih baris kosong di antaranya.
3. Untuk jeda baris, paragraf harus diperbaiki setelahnya dengan dua spasi kosong (atau setara tabnya), atau garis miring terbalik ( \ ).

• Tutorial interaktif untuk belajar tentang paragraf.
• Permalink Dingus lihat contoh lengkapnya dengan Pratinjau dan AST.
• Pelajari lebih lanjut tentang paragraf.

Judul

Headings in Markdown mewakili salah satu elemen Heading HTML. Ada dua cara untuk mendefinisikan heading:

1. pos ATX.
2. Judul setteks.

Aturan berikut menentukan heading ATX:

1. Heading level 1 ( h1 ), hingga heading level 6, ( h6 ) didukung.
2. Judul gaya Atx diawali dengan simbol hash ( # ).
3. Setidaknya harus ada ruang kosong yang memisahkan teks dan simbol hash ( # ).
4. Hitungan hash setara dengan nomor kardinal judul. Satu hash adalah h1 , dua hash, h2 , 6 hash, h6 .
5. Dimungkinkan juga untuk menambahkan jumlah simbol hash yang berubah-ubah ke judul, meskipun ini tidak menimbulkan efek apa pun (yaitu # Heading 1 # )

Aturan berikut menentukan judul Setext:

1. Hanya Heading level 1 (h1), dan heading level 2, (h2) yang didukung.
2. Definisi gaya settext dilakukan dengan simbol sama dengan (=) dan tanda hubung masing-masing.
3. Dengan Setext, setidaknya satu simbol sama dengan atau tanda hubung diperlukan.

• Tutorial interaktif untuk mempelajari heading.
• Permalink Dingus untuk melihat contoh lengkap dengan Pratinjau dan AST.
• Pelajari lebih lanjut tentang judul ATX.
• Pelajari lebih lanjut tentang judul Setext.

Penekanan Dan Penekanan Kuat

Penekanan dalam Markdown dapat berupa miring atau tebal (penekanan kuat).

Aturan berikut mendefinisikan penekanan:

1. Penekanan biasa dan kuat dirender dalam HTML masing-masing sebagai elemen Penekanan, <em>, dan Kuat, <strong>.
2. Teks yang dibatasi oleh satu tanda bintang ( * ) atau garis bawah ( _ ) akan menjadi penekanan.
3. Teks yang dibatasi oleh tanda bintang ganda atau garis bawah akan menjadi penekanan yang kuat.
4. Simbol pembatas (tanda bintang atau garis bawah) harus cocok.
5. Tidak boleh ada spasi antara simbol dan teks terlampir.

• Tutorial interaktif untuk belajar tentang penekanan.
• Permalink Dingus untuk melihat contoh lengkap dengan Pratinjau dan AST.
• Pelajari lebih lanjut tentang Penekanan dan penekanan kuat.

Aturan Horisontal

Aturan Horizontal, <hr/> dibuat dengan tiga atau lebih tanda bintang ( * ), tanda hubung ( - ), atau garis bawah ( _ ), pada baris baru. Simbol dipisahkan oleh sejumlah spasi, atau tidak sama sekali.

• Permalink Dingus untuk melihat contoh lengkap dengan Pratinjau dan AST.
• Pelajari lebih lanjut tentang jeda Tematik.

Daftar

Daftar dalam penurunan harga adalah daftar peluru (tidak berurutan) atau daftar berurutan.

Aturan berikut menentukan daftar:

1. Daftar peluru dirender dalam HTML sebagai elemen daftar Tidak Terurut, <ul>.
2. Daftar terurut dirender dalam HTML sebagai elemen Daftar terurut, <ol>.
3. Daftar poin menggunakan tanda bintang, plus, dan tanda hubung sebagai penanda.
4. Daftar berurutan menggunakan angka yang diikuti dengan titik atau kurung tutup.
5. Penanda harus konsisten (Anda hanya boleh menggunakan penanda yang Anda gunakan untuk memulai definisi item daftar lainnya).

• Tutorial interaktif untuk mempelajari tentang daftar.
• Permalink Dingus untuk melihat contoh lengkap dengan Pratinjau dan AST.
• Pelajari lebih lanjut tentang item Daftar.

Tautan

Tautan didukung dengan format inline dan referensi .

Aturan berikut menentukan tautan:

1. Tautan dirender sebagai elemen Jangkar HTML, <a>.
2. Format inline memiliki sintaks: [value](URL "optional-title") tanpa spasi di antara tanda kurung.
3. Format referensi memiliki sintaks: [value][id] untuk referensi, dan [id]: href "optional-title" untuk label hyperlink, dipisahkan dengan setidaknya satu baris.
4. id adalah Definition Identifier dan dapat terdiri dari huruf, angka, spasi, dan tanda baca.
5. Pengidentifikasi Definisi tidak peka huruf besar/kecil.
6. Ada juga dukungan untuk Tautan Otomatis, di mana URL dibatasi oleh simbol kurang dari (<) dan lebih besar dari (>), dan ditampilkan secara harfiah.

 <!--Markdown--> [Google](https://google.com “Google”) <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> [Google](https://google.com) <!--Rendered HTML--> <a href="https://google.com">Google</a> <!--Markdown--> [Comparing Styling Methods in Next.js](/2020/09/comparing-styling-methods-next-js) <!--Rendered HTML--> <a href="/2020/09/comparing-styling-methods-next-js">Comparing Styling Methods In Next.js</a> <!--Markdown--> [Google][id] <!--At least a line must be in-between--> <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> <https://google.com> <!--Rendered HTML--> <a href="https://google.com">google.com</a> <!--Markdown--> <[email protected]> <!--Rendered HTML--> <a href="mailto:[email protected]">[email protected]</a>

• Tutorial interaktif untuk mempelajari tentang tautan.
• Permalink Dingus untuk melihat contoh lengkap dengan Pratinjau dan AST.
• Pelajari lebih lanjut tentang Tautan.

Gambar-gambar

Gambar dalam Penurunan Harga mengikuti format inline dan referensi untuk Tautan.

Aturan berikut menentukan gambar:

1. Gambar dirender sebagai elemen gambar HTML, <img>.
2. Format inline memiliki sintaks: ![alt text](image-url "optional-title") .
3. Format referensi memiliki sintaks: ![alt text][id] untuk referensi, dan [id]: image-url "optional-title" untuk label gambar. Keduanya harus dipisahkan oleh setidaknya satu baris kosong.
4. Judul gambar bersifat opsional, dan url gambar dapat bersifat relatif.

 <!--Markdown--> ![alt text](image-url "optional-title") <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" /> <!--Markdown--> ![alt text][id] <!--At least a line must be in-between--> <!--Markdown--> <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" />

• Tutorial interaktif untuk belajar tentang gambar.
• Permalink Dingus untuk melihat contoh lengkap dengan Pratinjau dan AST.
• Pelajari lebih lanjut tentang Gambar.

Blockquote

Elemen Kutipan Blok HTML, <blockquote>, dapat dibuat dengan mengawali baris baru dengan simbol lebih besar dari ( > ).

 <!--Markdown--> > This is a blockquote element > You can start every new line > with the greater than symbol. > That gives you greater control > over what will be rendered. <!--Rendered HTML--> <blockquote> <p>This is a blockquote element You can start every new line with the greater than symbol. That gives you greater control over what will be rendered.</p> </blockquote>

Blockquotes dapat disarangkan:

 <!--Markdown--> > Blockquote with a paragraph >> And another paragraph >>> And another <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <blockquote> <p>And another paragraph</p> <blockquote> <p>And another</p> </blockquote> </blockquote> </blockquote>

Mereka juga dapat berisi elemen penurunan harga lainnya, seperti header, kode, item daftar, dan sebagainya.

 <!--Markdown--> > Blockquote with a paragraph > # Heading 1 > Heading 2 > - > 1. One > 2. Two <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <h1>Heading 1</h1> <h2>Heading 2</h2> <ol> <li>One</li> <li>Two</li> </ol> </blockquote>

• Tutorial interaktif untuk belajar tentang blockquotes.
• Permalink Dingus untuk melihat contoh lengkap dengan Pratinjau dan AST.
• Pelajari lebih lanjut tentang Blockquotes.

Kode

Elemen Kode Sebaris HTML, <code>, juga didukung. Untuk membuatnya, batasi teks dengan tanda centang kembali (`), atau tanda centang kembali ganda jika perlu tanda centang kembali secara literal dalam teks terlampir.

 <!--Markdown--> `inline code snippet` <!--Rendered HTML--> <code>inline code snippet</code> <!--Markdown--> `<button type='button'>Click Me</button>` <!--Rendered HTML--> <code><button type='button'>Click Me</button></code> <!--Markdown--> `` There's an inline back-tick (`). `` <!--Rendered HTML--> <code>There's an inline back-tick (`).</code>

• Tutorial interaktif untuk belajar tentang kode.
• Permalink Dingus untuk melihat contoh lengkap dengan Pratinjau dan AST.
• Pelajari lebih lanjut tentang rentang Kode.

Blok Kode

Elemen Teks Preformated HTML, <pre>, juga didukung. Ini dapat dilakukan dengan setidaknya tiga dan jumlah yang sama dari back-tick ( ` ), atau tilde ( ~ ) — biasanya disebut sebagai code-fence, atau indentasi awal baris baru setidaknya 4 spasi.

 <!--Markdown--> ``` const dedupe = (array) => [...new Set(array)]; ``` <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre> <!--Markdown--> const dedupe = (array) => [...new Set(array)]; <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre>

• Tutorial interaktif untuk belajar tentang kode.
• Permalink Dingus untuk melihat contoh lengkap dengan Pratinjau dan AST.
• Pelajari lebih lanjut tentang blok kode Pagar dan Indentasi.

Menggunakan HTML Sebaris

Menurut catatan spesifikasi asli John Grubers pada HTML sebaris, markup apa pun yang tidak tercakup oleh sintaks Markdown, Anda cukup menggunakan HTML itu sendiri, dengan Satu-satunya batasan adalah elemen HTML tingkat blok — misalnya <div> , <table> , <pre> , <p> , dll. — harus dipisahkan dari konten di sekitarnya dengan baris kosong, dan tag awal dan akhir blok tidak boleh diindentasi dengan tab atau spasi.

Namun, kecuali Anda mungkin salah satu orang di belakang CommonMark itu sendiri, atau sekitar itu, kemungkinan besar Anda akan menulis Penurunan harga dengan rasa yang sudah diperluas untuk menangani sejumlah besar sintaks yang saat ini tidak didukung oleh CommonMark.

Maju

CommonMark adalah pekerjaan yang terus berjalan dengan spesifikasi terakhir diperbarui pada 6 April 2019. Ada sejumlah aplikasi populer yang mendukungnya di kumpulan alat penurunan harga. Dengan kesadaran akan upaya CommonMark menuju standardisasi, saya pikir cukup untuk menyimpulkan bahwa dalam kesederhanaan Markdown, ada banyak pekerjaan yang terjadi di belakang layar dan itu adalah hal yang baik untuk upaya CommonMark bahwa spesifikasi formal GitHub Flavoured Markdown didasarkan pada spesifikasi.

Langkah menuju upaya standarisasi CommonMark tidak mencegah penciptaan rasa untuk memperluas sintaks yang didukung, dan saat CommonMark bersiap untuk rilis 1.0 dengan masalah yang harus diselesaikan, ada beberapa sumber daya menarik tentang upaya berkelanjutan yang dapat Anda gunakan untuk teliti.

Sumber daya

• Memperkenalkan Penurunan Harga oleh John Gruber
• Situs web resmi CommonMark
• Spesifikasi Penurunan Harga Rasa GitHub
• cmark repo resmi
• Garpu cmark GitHub
• Penurunan harga di Wikipedia
• Panduan penurunan harga