Markdown ke HTML: alur kerja penerbitan yang bersih

Alur penerbitan membutuhkan format master yang bertahan melintasi alat, hosting, dan desain ulang. Markdown teks polos adalah master itu: terbaca di editor mana pun, bisa di-diff di version control, dan independen dari template HTML apa pun yang kebetulan merendernya tahun ini.

Disiplin yang membuatnya berhasil adalah aliran satu arah: Markdown diedit tangan, HTML diproduksi konverter, dan tidak ada yang menambal output secara manual. Begitu HTML hasil ekspor mendapat edit tangan, ada dua master, dan keduanya akan berbeda arah.

• PortabelPortabilitas: file Markdown terbuka di setiap editor dan terkonversi ke HTML, PDF, slide, atau sistem dokumentasi tanpa proyek migrasi.
• Bisa di-diffKeterbacaan review: perubahan prosa tampil sebagai diff baris yang bersih, sementara master HTML mengubur edit satu kata di dalam tag dan atribut.
• Struktur, bukan gayaPemisahan kepentingan: sumber membawa struktur—judul, daftar, kutipan—sementara tema menentukan tipografi, sehingga desain ulang tidak pernah menyentuh arsip.

Konverter yang disengaja mendukung subset dengan sengaja, karena setiap konstruksi yang didukung adalah satu cara lagi menyelundupkan markup yang tidak direview siapa pun. Ketahui di mana konten Anda berdiri relatif terhadap garis itu sebelum mengandalkan konversi.

Dalam mode Markdown-ke-HTML, sintaks gambar hanya mempertahankan teks alt, bukan gambar atau URL-nya; HTML mentah di-escape sebagai teks. Dalam mode HTML-ke-Markdown, tabel yang ditempel menjadi blok teks berpagar dan kehilangan grid. Periksa hasil konversi sebelum menerbitkan.

• Konversi bersihTerkonversi bersih: judul hingga enam level, paragraf, tebal, miring, coretan, kode inline, blok kode berpagar, daftar berurut dan tak berurut, blockquote, garis horizontal, dan tautan inline.
• Kerugian yang diketahuiDi luar subset yang didukung, hasilnya bergantung pada arah konversi: sintaks gambar Markdown hanya mempertahankan teks alt, HTML mentah dalam Markdown di-escape sebagai teks, dan tabel HTML menjadi blok teks berpagar saat dikonversi kembali ke Markdown. Periksa catatan kaki dan daftar tugas pada hasilnya, jangan menganggapnya pasti bertahan.
• Uji artikel nyataUjiannya sederhana: konversikan satu artikel representatif dan baca outputnya. Apa pun yang hilang dari hasil memang tidak pernah ada dalam kontrak.

HTML hasil konversi mungkin dimasukkan ke halaman, sehingga ruang kerja melakukan sanitasi secara bawaan. Elemen aktif dihapus, tag tak dikenal dibuka menjadi teks, dan atribut dibuang kecuali URL tautan yang diizinkan serta nilai awal daftar bernomor yang valid.

Panel pratinjau merender output yang telah disanitasi dan tidak pernah memuat sumber daya jarak jauh, sehingga menempelkan markup jahat pun tidak bisa membuat alat itu sendiri menelepon pulang.

• Konten aktif dihapusElemen pembawa perilaku aktif—script, style, iframe, object, embed, svg, form, video, audio, img—dihapus beserta isinya, bukan sekadar dinetralkan.
• Atribut dilucutiStyle inline, event handler, dan class sumber dihapus. Tautan yang aman mempertahankan href, dan daftar bernomor yang valid mempertahankan start.
• Dilaporkan, bukan diamRuang kerja melaporkan apa yang dihapus—jumlah node yang dibuang dan atribut yang dilucuti—sehingga sanitasi adalah peristiwa yang terlihat, bukan mutasi diam-diam.

Dokumen hasil render sebagian besar adalah tautan, dan tautan adalah tempat sanitasi menjadi spesifik. Konverter menerima URL http, https, dan mailto plus #fragmen dalam halaman; apa pun selain itu—javascript:, data:, trik protokol-relatif—kehilangan href-nya dan dirender sebagai teks polos.

Periksa daftar izin terhadap konten Anda sebelum menstandarkan konverter: set dokumentasi yang secara sah menaut ke mirror FTP atau skema aplikasi kustom perlu mempertahankan tautan itu secara manual, karena sanitizer yang waras tidak akan meloloskannya otomatis.

• Daftar skema yang diizinkanTautan yang selamat dicap rel="noreferrer noopener", sehingga tautan yang diikuti tidak bisa melihat atau men-skrip halaman asalnya.
• noopener noreferrerAturan yang sama berlaku dua arah: tautan yang ditulis dalam Markdown diperiksa saat konversi, dan href yang ditemukan dalam HTML tempel diperiksa ulang setelah sanitasi.
• Label bertahanBila tautan kehilangan skemanya, teks labelnya tetap ada—navigasi rusak langsung terlihat, alih-alih mengirim payload javascript: yang diam-diam.

Mengonversi HTML ke Markdown adalah upaya mengambil kembali konten, bukan putaran tanpa kehilangan. Judul, paragraf, penekanan, daftar, kutipan, dan kode yang didukung kembali sebagai Markdown. Struktur lain dapat disederhanakan atau dihapus oleh sanitasi dan konversi.

Perlakukan HTML-ke-Markdown sebagai cara menarik prosa keluar dari halaman yang tidak lagi Anda kendalikan—ekspor CMS lama, dokumen yang hanya tersisa sebagai HTML terender. Lalu perbaiki yang tidak bisa diperbaiki perjalanan pulang: tambahkan lagi gambarnya, bangun ulang tabelnya, dan mulai saat itu jadikan Markdown sebagai master.

• Tabel runtuhTabel kehilangan grid dan menjadi blok teks berpagar, sehingga data tabular perlu disusun ulang atau diekspor sebagai CSV.
• Media dihapusGambar, video, dan embed interaktif hilang by design—sanitizer menghapusnya sebagai konten aktif sebelum Markdown dibangun.
• Teks hidup lebih lama dari gayaFormat di luar subset—span, div, class, target anchor—tidak meninggalkan jejak; teks selamat, presentasi tidak.

Langkah konversi berjalan saat terbit, sekali per artikel: draft dan review dalam Markdown, konversi ke HTML tersanitasi, verifikasi hasil render, lalu kirim. Semuanya terjadi di tab browser—draft tidak pernah diunggah, yang penting bila kontennya adalah peluncuran yang belum diumumkan.

• Langkah saat terbitRuang kerja menerima sumber hingga 256 KiB dan menghasilkan output hingga 512 KiB—cukup untuk skala satu bab buku—dan melaporkan error eksplisit saat melewati batas itu alih-alih memotong diam-diam.
• Batas eksplisitSalin output ke kolom CMS Anda atau unduh sebagai file; kedua jalur mengambil dokumen tersanitasi yang sama dengan yang ditampilkan pratinjau.
• Konversi ulang, jangan tambalSimpan Markdown di version control di samping kode yang didokumentasikannya, dan konversi ulang setelah setiap edit alih-alih menambal HTML lama.