Ubah Markdown ke HTML

Potongan atau halaman, dan mana yang Anda perlukan

Ada dua hasil yang berguna, dan keduanya tidak bisa saling menggantikan. Potongan (fragment) hanyalah markup hasil konversi — judul, paragraf, daftar, tautan — tanpa pembungkus dokumen, dan itulah yang Anda perlukan bila hasilnya akan masuk ke template, kolom CMS, atau halaman lain. Halaman lengkap menambahkan doctype, head, deklarasi character set, dan stylesheet, sehingga bisa dibuka sendiri dan tampil layak. Menempel halaman lengkap ke CMS menghasilkan dokumen di dalam dokumen; membuka potongan di browser menghasilkan teks tanpa gaya.

Konversi ini mencakup set Markdown lanjutan yang sudah disepakati luas: judul, penekanan, daftar, tautan, gambar, kutipan blok, tabel, blok kode dengan syntax highlighting, daftar tugas, coret, dan catatan kaki. Judul mendapat pengenal yang diambil dari teksnya, sehingga bisa ditautkan langsung — tautan anchor yang membuat dokumentasi panjang enak dipakai.

HTML mentah di dalam Markdown diteruskan apa adanya. Itu bagian dari spesifikasinya, dan perlu disikapi dengan sadar: artinya file Markdown dari sumber yang tidak tepercaya bisa berisi tag script, dan mengonversinya menghasilkan halaman yang membawa script itu. Jangan pernah merender Markdown dari orang asing tanpa membersihkan HTML-nya setelah itu — konversi bukanlah batas keamanan dan memang tidak pernah dimaksudkan begitu.

Dua hal sengaja dikeluarkan sebagai blok kode, bukan dirender. Rumus matematika dalam notasi LaTeX membutuhkan library typesetting, dan diagram Mermaid membutuhkan renderer diagram — masing-masing merupakan dependensi besar, dan persamaan yang salah render lebih buruk daripada persamaan yang terlihat apa adanya. Halaman lengkap memakai font sistem biasa tanpa mengunduh font apa pun, jadi bisa dipakai offline dan tampil sedikit berbeda di Windows, macOS, dan Linux.

Jika Anda butuh hal lain

Pandoc menangani bagian yang tidak dicakup di sini, dan jauh lebih banyak lagi: pandoc in.md -o out.html --mathjax --standalone --toc merender matematika dengan benar, membuat daftar isi, dan menerima template sehingga hasilnya cocok dengan situs Anda sendiri. Pandoc juga bisa mengonversi dari dan ke sekitar empat puluh format lain, itulah sebabnya layak diinstal sekali.

Untuk sebuah situs web, bukan sekadar file, gunakan generator alih-alih mengonversi halaman satu per satu. Hugo, Eleventy, Jekyll, dan MkDocs mengubah satu folder Markdown menjadi situs dengan navigasi, pencarian, dan gaya yang seragam, lalu membangunnya ulang setiap kali sumbernya berubah — dan itulah pekerjaan sebenarnya begitu dokumennya lebih dari satu.