Pengonversi HTML ke Markdown

Apa yang Sebenarnya Dilakukan Konversi HTML-ke-Markdown

Konverter HTML-ke-Markdown mem-parse fragmen HTML, berjalan melalui pohon DOM yang dihasilkan, dan memancarkan sintaks Markdown untuk setiap elemen yang dikenalinya. <h1> menjadi #; <strong> menjadi **bold**; <a href="..."> menjadi [text](url); <ul><li> menjadi daftar berbutir. Alat ini berjalan sepenuhnya di browser Anda melalui JavaScript: tempel HTML di kiri, klik Convert to Markdown, dan output yang diformat muncul di kanan. Tidak ada upload, tidak ada round-trip server, tidak ada telemetri: verifikasi di tab Network DevTools saat Anda mengklik Convert, atau bawa halaman offline (mode pesawat) setelah dimuat dan konverter masih berfungsi. Implementasi ini menggunakan DOMParser built-in browser untuk membaca HTML, kemudian walker rekursif kecil memancarkan Markdown untuk setiap node. Itu adalah konverter ~150-baris yang ditulis tangan daripada wrapper di sekitar Turndown, yang berarti itu mencakup kasus umum dengan bersih tetapi tidak cocok dengan konfigurabilitas penuh Turndown.

Kapan Anda Sebenarnya Memerlukan Konversi Ini

Arah terbalik (Markdown ke HTML) adalah yang terkenal: setiap generator situs statis dan alat penulisan melakukannya. Arah maju (HTML ke Markdown) kurang jelas tetapi semakin umum karena ekosistem alat-penulisan telah terpolarisasi: HTML adalah format ambient web (setiap CMS, platform newsletter, template CRM, situs statis lama memancarkan atau menyimpan HTML); Markdown adalah format native dari setiap dokumentasi modern, pencatatan, dan alur kerja konten-yang-dikontrol-sumber yang muncul sejak sekitar 2014. Empat alur kerja dunia nyata menghasilkan kebutuhan konversi ini.

• Scraping artikel untuk aplikasi pencatatan. Menyimpan artikel web ke Obsidian, Notion, Logseq, atau Roam: semua menyimpan catatan sebagai file Markdown. Web Clipper resmi Obsidian (dirilis 2024) dan ekstensi browser MarkDownload yang populer mengikuti pola ini: ekstrak DOM artikel dengan pustaka Readability Mozilla, konversi ke Markdown, simpan ke disk. Ketika Anda tidak dapat menjangkau HTML yang mendasarinya melalui ekstensi (konten berbayar, pembaca tertanam, konten yang tiba melalui email), salin teks yang dirender, tempel HTML yang dihasilkan ke konverter, simpan Markdown.
• Migrasi CMS ke SSG Markdown-first. Memindahkan dokumentasi dari WordPress, Confluence, Drupal, Mediawiki, atau Movable Type ke MkDocs (Tom Christie, Python), Docusaurus (Meta, React), Hugo (Steve Francia, Go), Jekyll (Tom Preston-Werner, Ruby: masih mesin di balik GitHub Pages), Eleventy (Zach Leatherman, Node), VitePress (Evan You, Vue), atau Sphinx-with-MyST. Semua ini Markdown-native; konten CMS yang ada harus diekspor sebagai HTML dan dikonversi secara massal.
• Output editor WYSIWYG ke Markdown portabel. Penulis menggunakan Google Docs, Word, Apple Notes, Evernote atau editor rich-text CMS dan payload clipboard adalah HTML. Mereka menginginkan Markdown bersih untuk di-commit ke Git, ditempel ke editor Markdown, dikirim ke pengembang, atau dimasukkan ke situs docs. "Save as Web Page" Microsoft Word menghasilkan HTML yang terkenal padat: penuh dengan namespace XML, CSS dengan prefiks mso-, tag khusus-Office: dan konverter yang mengabaikan apa pun yang tidak dipahami dan memancarkan Markdown bersih adalah persis alat pembersihan yang tepat.
• Konten email untuk arsip. Platform newsletter (Substack, Kit/ConvertKit, Beehiiv, Mailchimp) semua mengirim HTML yang diformat. Pembaca yang menyimpan materi referensi dalam Markdown dapat melihat-sumber pada body email, menempel HTML ke konverter, dan mengarsipkan hasilnya ke catatan mereka.

Implementasi Referensi: Turndown dan Keluarganya

Turndown (Dom Christie) adalah pustaka HTML-ke-Markdown JavaScript yang dominan: itu dimulai sebagai to-markdown pada 2012, diganti namanya menjadi Turndown pada 2017 untuk membedakan dari fork, dan diterbitkan sebagai turndown di npm di bawah lisensi MIT. Desainnya berbasis-aturan: setiap aturan memiliki filter (node DOM mana aturan berjalan) dan replacement (fungsi yang menghasilkan Markdown). Konstruktor menerima opsi untuk gaya heading (atx # vs setext ===), marker bullet (-, +, atau *), gaya code block (terindentasi vs fenced), pembatas penekanan (* vs _), pembatas strong (** vs __), gaya tautan (inline vs reference) dan seterusnya. Tabel, strikethrough, item daftar tugas, dan autolinks tinggal di paket terpisah turndown-plugin-gfm. markdownify (Matthew Tretter) adalah ekuivalen di Python: banyak digunakan dalam pipeline scraping, konversi notebook Jupyter, document loaders LangChain, dan persiapan dataset LLM. html2text (awalnya oleh Aaron Swartz, yang juga berkolaborasi dengan John Gruber pada desain Markdown asli pada 2004) adalah opsi Python yang lebih lama, masih digunakan dalam pipeline email legacy tetapi sebagian besar telah digantikan. html-to-markdown (Johannes Kaufmann) adalah port Go dari Turndown yang populer untuk biner scraping mandiri. Pandoc (John MacFarlane, yang memimpin proyek CommonMark) adalah konverter dokumen universal: menangani tabel dengan sel yang digabungkan melalui grid table, matematika, kutipan, catatan kaki, daftar definisi, dan mengonversi antara puluhan format. Pandoc adalah alat HTML-ke-Markdown paling kaya fitur yang tersedia, tetapi itu adalah biner Haskell 60+ MB yang harus diinstal; itu tidak berjalan di browser.

Trade-off Fundamental: HTML Lebih Kaya dari Markdown

Setiap konversi HTML-ke-Markdown selalu lossy karena format sumber mengekspresikan hal-hal yang tujuan tidak bisa. Style inline (<span style="color:red">) tidak memiliki tata bahasa Markdown: kosakata penekanan Markdown ketat bold/italic/strikethrough/code, tanpa sintaks untuk warna, font, atau ukuran sembarang. Kelas CSS (<div class="alert">) membawa makna ke stylesheet tetapi tidak ada ke Markdown. Atribut data custom (data-track-event="...") adalah bagian dari kontrak JavaScript halaman, bukan dokumen. Tabel dengan sel yang digabungkan (colspan, rowspan) tidak dapat diekspresikan dalam tabel pipe GFM. Media tertanam (<video>, <audio>, <iframe>) dan kontrol formulir tidak memiliki ekuivalen Markdown. <details><summary> yang dapat diciutkan, <figure><figcaption>, anotasi <ruby> untuk pelafalan CJK, microdata, dan microformats: tidak ada yang bertahan dari konversi. Untuk setiap konstruksi yang tidak didukung, penulis konverter memilih salah satu dari tiga strategi: terjemahkan ke perkiraan Markdown yang kehilangan beberapa informasi, lewatkan sebagai HTML mentah yang tertanam di dalam Markdown (Markdown mengizinkan ini per spec; CommonMark bagian 4.6 dan 6.6 mencakupnya), atau jatuhkan sepenuhnya. Implementasi ini memilih "terjemahkan di mana ada pemetaan yang jelas, jika tidak transparent-wrap (render anak-anak, jatuhkan tag)": default yang dapat diprediksi dan mudah dipikirkan yang menangani kasus umum dengan biaya konfigurabilitas lanjutan.

Pemetaan Kanonis

• Heading: <h1>-<h6> dipetakan ke # melalui ###### (gaya atx). Bentuk setext yang lebih lama (garis bawah === dan ---) juga valid untuk h1 dan h2 tetapi jarang digunakan pada 2026.
• Paragraf: <p> menjadi teks biasa dengan baris kosong di sekitarnya. Pemecah paragraf dalam Markdown adalah satu atau lebih baris kosong.
• Penekanan: <strong> dan <b> menjadi **bold**. <em> dan <i> menjadi *italic*. <del> dan <s> menjadi ~~strikethrough~~ (ekstensi GFM; bukan dalam CommonMark proper).
• Tautan: <a href="url">text</a> menjadi [text](url). Bentuk reference-link ([text][1] dengan [1]: url di bagian bawah) juga merupakan Markdown yang valid.
• Gambar: <img src="url" alt="text"> menjadi ![text](url). Tanda seru membedakan gambar dari tautan.
• Kode: <code> menjadi span backtick inline. <pre><code> menjadi blok fenced triple-backtick. Implementasi ini dengan benar menangani persyaratan CommonMark bahwa span kode inline menggunakan fence yang lebih panjang ketika konten berisi backtick (cocok dengan aturan spec dari CommonMark §6.1).
• Daftar: <ul> menjadi baris berbutir -; <ol> menjadi baris bernomor 1., 2., ... CommonMark menerima nomor awal apa pun; renderer menormalkan.
• Blockquote: <blockquote> menambahkan prefiks > ke setiap baris anak.
• Garis horizontal: <hr> menjadi --- di barisnya sendiri. *** dan ___ juga valid.
• Pemecah baris: <br> menjadi baris baru. CommonMark juga menerima dua spasi trailing atau backslash di akhir baris.
• Tabel: <table> menjadi tabel pipe GFM: baris header, baris pembatas ---, baris body. Ekstensi GFM; bukan dalam inti CommonMark.

Lingkup Jujur: Apa yang Dilakukan dan Tidak Dilakukan Alat Ini

Tiga keterbatasan jujur untuk diketahui. (1) Style inline dan kelas CSS dijatuhkan. <span style="color:red"> menjadi teks tidak terstilisasi; <p class="lede"> kehilangan kelasnya. Tidak ada tata bahasa Markdown untuk styling inline sembarang. (2) Tabel dengan sel yang digabungkan menjadi datar. Tabel pipe GFM tidak memiliki sintaks untuk colspan atau rowspan; informasi sel yang digabungkan dijatuhkan secara diam-diam. Untuk tabel kompleks, simpan sumber sebagai HTML di dalam Markdown (CommonMark mengizinkan HTML tertanam) atau gunakan Pandoc untuk output grid-table. (3) Blok kode dipancarkan tanpa petunjuk bahasa. Jika HTML Anda berisi <pre><code class="language-js">, atribut bahasa saat ini dijatuhkan: output adalah blok fenced tanpa-bahasa. Anda dapat menambahkan pengidentifikasi bahasa secara manual setelah backtick pembuka jika renderer tujuan Anda mendukung penyorotan sintaks. Caveat yang lebih besar: jika Anda menempel HTML lengkap dari halaman web (dari "View Page Source"), konten <script> dan <style> akan dipancarkan sebagai teks biasa: hampir pasti bukan yang Anda inginkan. Perbaikannya adalah menempel hanya konten artikel, atau menyalin dari tampilan yang dirender (yang melucuti script dan style secara otomatis), atau menyanitasi HTML melalui DOMPurify atau serupa sebelum konversi.

Bentuk Markdown pada 2026

Markdown berusia dua puluh dua tahun pada 2026. John Gruber menerbitkan skrip Perl asli pada 2004 dengan Aaron Swartz sebagai kolaborator desain. Tabel sengaja dihilangkan dari asli Gruber; sintaks tabel pipe yang akrab bagi sebagian besar pembaca hari ini berasal dari dialek-dialek selanjutnya, yang paling menonjol GitHub Flavored Markdown. CommonMark, upaya spesifikasi yang ketat yang diorganisir oleh Jeff Atwood dan John MacFarlane pada 2014, sekarang berada di versi 0.31.2 (28 Januari 2024) dan merupakan dialek yang paling dituju oleh sebagian besar parser modern. GitHub Flavored Markdown (GFM, diformalkan dalam versi 0.29-gfm pada 6 April 2019) adalah superset GFM yang menambahkan tabel, daftar tugas, strikethrough, autolinks, dan aturan disallowed-raw-HTML. GFM adalah dialek yang sebagian besar pengguna sebenarnya lihat di web karena skala GitHub. Markdown sekarang adalah format native dari pada dasarnya setiap ekosistem dokumentasi pengembang; HTML tetap menjadi format output universal web; konversi di antara mereka persis sama umum dengan inversnya, dan ada untuk saat ketika Anda membutuhkannya dengan cepat, di browser, tanpa instalasi dan tanpa data meninggalkan perangkat Anda.

Privasi: Mengapa Hanya-Browser Penting di Sini

HTML yang ditempel ke konverter sering berisi jejak sumber asli: markup CMS internal, konten draf yang belum diterbitkan, data pelanggan di dalam template email, URL tautan yang mengungkapkan struktur situs internal, referensi gambar yang menunjuk ke server aset pribadi. Konverter sisi-server mengunggah semuanya ke layanan pihak-ketiga. Alat ini berjalan sepenuhnya di browser Anda melalui JavaScript: HTML yang Anda tempel tidak pernah melintasi jaringan: verifikasi di tab Network DevTools saat Anda mengklik Convert, atau bawa halaman offline (mode pesawat) setelah dimuat dan konverter masih berfungsi. Aman untuk draf yang belum diterbitkan, template email pelanggan, ekstrak dokumentasi internal, atau HTML apa pun yang tidak ingin Anda salin ke hard drive orang asing.

Pertanyaan yang Sering Diajukan

Apakah ini berfungsi dengan file besar?

Ya: karena konversi berjalan di browser Anda, plafon praktis adalah memori yang tersedia perangkat Anda. Puluhan ribu baris dikonversi dalam waktu kurang dari satu detik di laptop modern. Input yang sangat besar (jutaan node) dapat sebentar membekukan tab saat walker DOM rekursi. Untuk konversi batch dari ekspor CMS lengkap, skrip yang menggunakan Turndown di Node atau markdownify di Python adalah alat yang lebih baik.

Apa yang terjadi pada style inline dan kelas CSS?

Dijatuhkan sepenuhnya. Tata bahasa penekanan Markdown mencakup bold, italic, strikethrough, dan kode; tidak ada sintaks untuk warna, font, ukuran, atau styling yang didorong-kelas sembarang. Jika styling visual penting dalam output Anda, baik simpan asli sebagai HTML atau gunakan format tujuan yang lebih kaya seperti AsciiDoc, reStructuredText, atau MDX (Markdown plus komponen JSX, digunakan oleh Docusaurus). Untuk kasus penggunaan arsip-artikel dan migrasi-CMS untuk apa alat ini dibangun, menjatuhkan style adalah perilaku yang benar: seluruh poin Markdown adalah melucuti kebisingan visual dan menjaga hanya struktur.

Apakah alat ini bekerja offline?

Ya: setelah halaman dimuat, konversi berjalan sepenuhnya dalam JavaScript di dalam browser Anda. Tidak ada panggilan jaringan selama konversi. Verifikasi di tab Network DevTools saat Anda mengklik Convert, atau bawa perangkat offline (mode pesawat) setelah halaman dimuat dan alat masih berfungsi.

Apakah ini Turndown?

Tidak. Turndown (pustaka Dom Christie) adalah implementasi referensi dalam JavaScript dan alat yang jelas untuk dijangkau dalam proyek Node, tetapi itu adalah dependensi substansial dengan konfigurabilitas penuh untuk gaya heading, marker bullet, gaya tautan, gaya code block, dan seterusnya. Alat dalam-browser ini adalah walker DOM yang ditulis-tangan lebih kecil: sekitar 150 baris: yang menargetkan kasus umum (heading, paragraf, penekanan, tautan, gambar, daftar, blockquote, fenced code, tabel dasar) tanpa permukaan konfigurasi. Untuk alur kerja yang dibangun untuk situs ini (konversi satu-kali di browser, tanpa instalasi), implementasi yang lebih kecil adalah bentuk yang tepat; untuk pipeline scraping produksi yang membutuhkan aturan yang dapat dikonfigurasi, Turndown tetap menjadi pilihan yang tepat.

Bagaimana tabel ditangani?

Sebagai tabel pipe GFM: baris header, baris pembatas dash, dan satu baris body per <tr>. Tabel pipe datar: mereka tidak dapat mewakili colspan, rowspan, konten sel multi-baris, daftar di dalam sel, atau perataan per-sel. Jika tabel HTML Anda menggunakan salah satu dari fitur tersebut, konverter ini memancarkan tabel pipe yang terdegradasi yang kehilangan struktur tambahan. Untuk tabel kompleks, dua opsi praktis: (a) simpan tabel sebagai HTML mentah di dalam Markdown: CommonMark mengizinkan HTML tertanam: dan percayalah bahwa renderer tujuan Anda akan meneruskannya; (b) gunakan Pandoc dengan output grid-table, yang dapat mengekspresikan sel yang digabungkan.

Bisakah saya menempel HTML lengkap halaman web?

Anda bisa, tetapi Anda mungkin tidak seharusnya. Sumber lengkap halaman web modern berisi tag <script> dengan kode JavaScript, blok <style> dengan CSS, tracking pixel, markup iklan, dan komentar template CMS. Konverter ini tidak melucuti konten script dan style secara eksplisit, sehingga semuanya berakhir sebagai teks biasa di output Markdown Anda. Pendekatan yang bersih: pilih hanya elemen artikel di DevTools (klik kanan artikel, "Inspect", lalu klik kanan node yang cocok di panel Elements dan "Copy outerHTML"), atau gunakan langkah ekstraksi konten (pustaka Readability Mozilla, atau bentuk paketnya di Firefox Reader View) sebelum menempel. Untuk alur kerja ekstensi-browser yang menangani langkah ekstraksi secara otomatis, lihat Obsidian Web Clipper atau MarkDownload.

Alat terkait