Pratinjau Markdown

Markdown yang mana, dan mengapa HTML-nya disanitasi

Markdown adalah sebuah keluarga, bukan satu spesifikasi, dan dialek yang dipakai di sini adalah set GitHub-flavoured yang disepakati luas: judul, penekanan, daftar, link, gambar, kutipan blok, tabel, blok kode berpagar dengan syntax highlighting, daftar tugas, coret, catatan kaki, dan link otomatis. Itulah yang ditulis hampir semua orang dan yang ada di sebuah README. Dialek yang lebih eksotis dan plugin khusus yang ditambahkan situs tertentu — blok admonition, shortcode, templating — tidak didukung, jadi dokumen yang ditulis untuk satu generator tertentu mungkin menampilkan sebagian sintaksnya secara harfiah.

HTML mentah dirender tetapi disanitasi terlebih dulu, dan bagian inilah yang perlu dipahami. Markdown sengaja mengizinkan HTML di dalamnya, artinya file Markdown dari mana pun bisa berisi tag script, event handler inline, iframe, atau link javascript:. Merendernya apa adanya berarti menjalankan kode orang asing di sesi Anda hanya karena Anda menempelkan README mereka untuk dilihat. Semua yang bisa dijalankan dibuang sebelum apa pun ditampilkan, sehingga format tetap ada dan kodenya tidak.

Ini pelajaran umum, bukan sekadar detail halaman ini. Setiap sistem yang merender Markdown kiriman pengguna — kotak komentar, wiki, tiket dukungan — sebenarnya merender HTML kiriman pengguna kecuali jika ia menyanitasinya, dan anggapan “ini cuma Markdown” adalah cara hal itu terlewat. Mengonversi Markdown bukanlah batas keamanan; langkah sanitasinya yang merupakan batas keamanan.

Yang Anda dapatkan adalah pratinjau isi, bukan tampilan situs tertentu. GitHub, GitLab, dan generator dokumentasi masing-masing menerapkan stylesheet, anchor judul, dan ekstensinya sendiri, sehingga file yang sama terlihat berbeda di masing-masing — struktur yang ditampilkan di sini adalah bagian yang disepakati semuanya. Tidak ada yang diambil, jadi gambar yang dirujuk lewat alamat web hanya dimuat jika server tersebut mengizinkannya, dan path relatif ke file di repository sama sekali tidak bisa di-resolve.

Jika Anda butuh hal lain

Untuk README yang sedang Anda tulis, lihat pratinjaunya di tempat README itu akan berada. Editor bawaan GitHub menampilkan pratinjau dengan rendering, ekstensi, dan anchor yang persis sama, dan GitHub CLI — gh markdown-preview — melakukannya secara lokal dengan renderer yang sama. Untuk dokumentasi, generatornya sendiri (MkDocs, Docusaurus, Hugo) punya pratinjau live-reload yang menampilkan styling dan navigasi yang sebenarnya, yaitu yang akan dilihat pembaca.

Untuk mengedit, bukan sekadar memeriksa, editor Markdown dengan panel langsung — Obsidian, Typora, VS Code dengan pratinjau bawaannya — lebih baik daripada menempelkan ke halaman setiap kali, karena pratinjaunya diperbarui saat Anda mengetik dan file tetap di tempatnya. Halaman ini untuk membaca Markdown milik orang lain, atau untuk melihat sekilas sesuatu yang dikirimkan kepada Anda.