Markdown ke HTML Konverter

Cara kerjanya

1. Tempel Markdown: masukkan teks Markdown apa pun, heading, paragraf, daftar, blok kode, tabel, kutipan, dan tautan.
2. Konversi: alat menguraikan Markdown dan menghasilkan HTML yang bersih dan semantik dengan penyusunan elemen yang baik.
3. Pratinjau atau salin: pratinjau rendering atau salin HTML mentah untuk ditempel ke CMS, situs web, atau template email Anda.

Sejarah Singkat Markdown

Markdown diciptakan oleh John Gruber, penulis di balik weblog Daring Fireball, dengan umpan balik desain substansial dari Aaron Swartz. Rilis publik pertama, versi 1.0, diumumkan di situs Gruber pada 9 Maret 2004; versi 1.0.1, rilis referensi kanonik, mengikuti pada 17 Desember 2004 dan masih merupakan versi yang ditautkan dari daringfireball.net/projects/markdown. Markdown adalah dua hal sekaligus sejak awal: sintaks pemformatan teks biasa dan skrip Perl asli yang mengonversinya ke HTML. Tujuan yang dinyatakan Gruber adalah agar teks sumber dapat dibaca apa adanya, sebuah dokumen Markdown yang dibuka di editor teks biasa harus terlihat seperti email yang diformat dengan cermat, bukan sup tag. Kendala keterbacaan itu adalah garis filosofis yang memisahkan Markdown dari format berbasis XML dan dari markup yang lebih berat seperti LaTeX, dan itu adalah alasan setiap perpanjangan kemudian harus berdebat untuk dirinya sendiri dalam hal seberapa buruk itu mengganggu sumber. Aaron Swartz sebelumnya telah menulis markup ringan terkait yang disebut atx (2002), yang berkontribusi pada gaya heading # dan ## yang sekarang akrab, kadang-kadang masih disebut "heading gaya atx" di dalam spesifikasi parser.

CommonMark, Memperbaiki Underspecification

Deskripsi sintaks asli Gruber tahun 2004 terkenal informal, dokumen prosa dengan contoh, bukan tata bahasa. Itu meninggalkan puluhan kasus tepi tidak ditentukan, dan Gruber tidak pernah merilis parser referensi selain skrip Perl-nya, yang perilakunya idiosinkratik dengan cara yang harus disalin atau ditimpa oleh implementer lain. Hasilnya pada awal 2010-an adalah bahwa GitHub, Reddit, Stack Overflow, Pandoc dan parser Discount C semuanya merender sumber Markdown yang sama sedikit berbeda. Pada 2012, co-founder Stack Overflow Jeff Atwood dan penulis Pandoc John MacFarlane memulai upaya untuk menulis spesifikasi nyata yang dapat diuji. Proyek diluncurkan secara publik pada September 2014 sebagai "Standard Markdown"; dalam beberapa hari Gruber keberatan dengan nama itu dalam email pribadi, Atwood menulis posting publik yang menjelaskan perubahan, dan proyek itu diubah menjadi "CommonMark". Rilis bernomor pertama datang pada 25 Oktober 2014. Versi yang dipublikasikan saat ini adalah CommonMark 0.31.2, dirilis 28 Januari 2024. Spek CommonMark tidak biasa karena ia sendiri adalah dokumen CommonMark, dengan 600+ test case yang dapat dieksekusi inline; parser mengklaim kepatuhan dengan melewati tes-tes itu. GitHub Flavored Markdown (GFM), spec formal pada versi 0.29-gfm bertanggal 6 April 2019, mendefinisikan lima ekstensi di atas CommonMark: tabel, item task list, strikethrough, autolinks untuk URL telanjang, dan HTML mentah yang tidak diizinkan (pembatasan keamanan yang menghapus tag berbahaya dari HTML yang disediakan penulis).

Parser Utama

marked.js dibuat oleh Christopher Jeffrey pada 2011 dan telah dipelihara oleh organisasi GitHub markedjs sejak 2018, sebuah desain single-pass, lexer-then-parser yang memprioritaskan kecepatan mentah; ~36k bintang dan proyek Markdown dengan bintang terbanyak di GitHub. Ini adalah parser yang digunakan alat ini untuk konversi. markdown-it diluncurkan pada 2014 oleh Vitaly Puzrin dan Alex Kocharin, mengiklankan 100% kepatuhan CommonMark dengan toggle GFM opsional ditambah ekosistem plugin yang agresif (markdown-it-footnote, markdown-it-emoji, markdown-it-attrs, markdown-it-anchor dan beberapa ratus lainnya). Ini adalah parser yang digunakan oleh preview Markdown bawaan VS Code, UI web GitLab, dan Eleventy. remark / unified.js bukan parser tunggal tetapi kerangka transformasi pohon, kolektif unified mendefinisikan spec pohon sintaks abstrak yang disebut mdast (Markdown AST); remark mem-parse Markdown ke mdast, plugin memanipulasi pohon, dan remark-rehype mengonversi mdast ke hast (HTML AST) untuk emisi. Lebih lambat dari marked tetapi jauh lebih dapat dikomposisikan; pengguna terkenal termasuk Prettier, Gatsby, MDN dan linter bahasa inklusif alex. Pandoc, dirilis oleh John MacFarlane pada 10 Agustus 2006, adalah konverter dokumen universal, ditulis dalam Haskell, mem-parse sekitar 30 format input, merender ke sekitar 40 format output; ada di mana-mana dalam penerbitan akademis dan teknis.

Pipeline MD-ke-HTML, Secara Mekanis

Parser Markdown biasanya bekerja dalam dua pass. Parsing tingkat blok membagi input menjadi struktur blok, paragraf, heading, daftar, code fences, blockquote, aturan horizontal, tabel. Batas blok ditentukan oleh baris kosong dan indentasi; melakukannya dengan benar adalah sebagian besar dari apa yang membuat parser CommonMark benar. Parsing inline kemudian berjalan melalui isi setiap blok dan mencocokkan sintaks inline: emphasis (*italic*, **bold**), tautan ([text](url)), span kode inline (`code`), gambar (![alt](url)), strikethrough (~~text~~ di GFM), dan autolink eksplisit (<https://example.com>). Parsing emphasis inline adalah bagian paling rumit dari spec Markdown manapun, CommonMark mendedikasikan beberapa halaman spec dan puluhan kasus uji untuk menentukan kapan *foo*bar* harus menghasilkan <em>foo</em>bar* versus *foo<em>bar</em>. Parser kemudian merender setiap token sebagai elemen HTML yang sesuai dan menggabungkan hasilnya. Pretty printing, indentasi, dan syntax highlighting blok kode dilapisi di atas oleh opsi rendering.

Mengapa Mengonversi MD ke HTML Sejak Awal?

• Impor CMS. Banyak CMS headless (Contentful, Sanity, Wagtail, Ghost) menerima HTML tetapi tidak Markdown. Membuat draft di Markdown dan mengonversi sekali pada waktu publikasi menjaga pengalaman pengeditan tetap menyenangkan.
• Komposisi email. Klien email merender HTML; sebagian besar tidak merender Markdown. Platform newsletter (Mailchimp, ConvertKit, Substack) biasanya menerima HTML yang ditempel ke editor mereka. Konversi draft Anda, tempel, kirim.
• Draft posting blog. Beberapa instalasi WordPress legacy tanpa plugin Markdown memerlukan HTML di body posting; beberapa halaman toko Shopify dan Webflow menerima HTML di field rich-text mereka.
• Snippet generator situs statis. Ketika Anda membutuhkan chunk HTML inline untuk shortcode Hugo, template Eleventy atau file MDX Next.js, mengonversi Markdown ke satu fragmen HTML lebih cepat daripada melawan pipeline konversi SSG sendiri.
• Berbagi catatan yang dirender. Menempelkan Markdown "yang dirender" ke Slack, Notion, Linear, ClickUp atau tujuan rich-text lainnya kadang-kadang menginginkan HTML di clipboard alih-alih Markdown mentah.
• Mengarsipkan dokumentasi. Menyimpan HTML yang dirender bersama sumber Markdown berarti arsip Anda dapat dibaca manusia di browser tanpa parser, berguna untuk pelestarian jangka panjang.

Opsi Output yang Layak Diketahui

Penggunaan downstream yang berbeda menginginkan hal yang berbeda dari HTML yang dikonversi. Dokumen lengkap vs fragmen. Dokumen HTML lengkap mencakup <!DOCTYPE html>, <html>, <head> dengan metadata, dan wrapper <body>, tepat ketika Anda akan menyimpan file sebagai .html dan membukanya di browser. Fragmen hanya konten body, tidak ada wrapper, tepat ketika Anda akan menempelkan ke field CMS yang sudah menyediakan struktur dokumen. Alat ini mengeluarkan fragmen secara default; bungkus dengan boilerplate Anda sendiri jika Anda memerlukan dokumen lengkap. Sanitisasi. Secara default parser Markdown melewatkan HTML mentah tanpa perubahan, jadi jika sumber Anda berisi <script>alert(1)</script>, tag script itu akan muncul di output. Untuk dokumen yang masuk ke sistem multi-pengguna, jalankan output melalui DOMPurify (Cure53, dimulai Februari 2014) sebelum menyuntikkan ke DOM. Untuk penggunaan pribadi sekali pakai, output mentah baik-baik saja. ID Header. Menghasilkan atribut id pada heading (di-slugify dari teks heading) memungkinkan Anda membangun daftar isi dengan tautan anchor. Algoritma slug yang tepat berbeda antar platform, GitHub menggunakan satu aturan, MkDocs yang lain, marked.js yang ketiga, sehingga tautan anchor dapat rusak ketika konten berpindah antar sistem. Hard line break. CommonMark memerlukan dua spasi trailing di akhir baris atau backslash untuk memaksa <br>; beberapa platform (Discord, GitHub issues) memperlakukan newline tunggal sebagai break. Pilihan tergantung pada gaya yang diharapkan dari sumber Anda.

Jebakan Umum

• Konversi smart-quote. Beberapa parser (atau lapisan pasca-pemrosesan seperti SmartyPants milik Gruber sendiri) mengganti kutipan lurus dengan kutipan tipografi melengkung secara default. Jika Anda perlu mempertahankan kutipan lurus (karena output Anda diparsing sebagai kode), periksa apakah transformasi ini dimatikan.
• Sensitivitas whitespace marker daftar. Mencampur - dan * dan + dalam daftar yang sama, mengindentasi paragraf kelanjutan daftar kurang dari yang diperlukan marker, atau menempatkan baris kosong antara item daftar dapat membalik daftar ketat menjadi daftar longgar (setiap item dibungkus tag <p>). Perbedaan visual dalam output dramatis.
• Autolink yang terlalu bersemangat. Autolinking gaya GFM mengubah URL telanjang apa pun menjadi tautan, yang biasanya yang Anda inginkan, tetapi dapat merusak URL yang berisi tanda kurung (terutama URL Wikipedia) atau tanda baca trailing.
• Tabel yang memerlukan escape. Karakter pipe di dalam sel tabel harus di-escape sebagai \|, jika tidak akan dibaca sebagai separator kolom. Menangkap siapa saja yang mencoba memasukkan contoh kode satu baris di dalam sel.
• Markdown dan HTML campuran. Markdown dirancang untuk melewatkan HTML sembarang, jadi menjatuhkan <div class="callout"> ke dalam file Markdown berfungsi. Tetapi saat Anda meletakkan sintaks Markdown di dalam blok HTML, parser berbeda: CommonMark memperlakukan sebagian besar blok HTML sebagai opaque; Markdown Extra memperkenalkan markdown="1" untuk memilih masuk ke parsing bersarang.
• ID heading antar platform. Algoritma slugify yang berbeda menghasilkan fragmen anchor yang berbeda untuk heading yang sama; tautan intra-dokumen dapat rusak ketika konten berpindah antar sistem.

Alat Ini vs Markdown Previewer

Absolutool mengirim dua alat terkait yang tumpang tindih pada parser yang sama. Markdown Previewer untuk pengeditan langsung, tulis Markdown di sebelah kiri, lihat output visual yang dirender di sebelah kanan, tidak ada konsep "output HTML". Markdown-to-HTML Converter ini untuk konversi sekali pakai, tempel Markdown, salin HTML mentah, tempel ke CMS atau klien email Anda. Gunakan previewer ketika Anda membuat draft dan membutuhkan umpan balik visual; gunakan konverter ini ketika Anda memiliki Markdown selesai dan membutuhkan HTML yang dapat Anda angkut ke tempat lain. Kedua alat menggunakan marked.js di bawah kap dan menerima dialek CommonMark + GFM yang sama, jadi perilaku konversi identik di antara keduanya.

Privasi: Mengapa Browser-Saja Penting di Sini

Draft tulisan yang belum dipublikasikan, posting blog yang sedang berlangsung, dokumentasi internal, deliverable klien di bawah NDA, bab manuskrip, makalah akademis, persis jenis teks yang tidak ingin Anda unggah ke layanan pihak ketiga. Konverter Markdown sisi server memerlukan pengiriman seluruh dokumen ke endpoint jarak jauh, yang berarti itu berada di log server, mungkin di cache CDN, mungkin di pipeline analitik, mungkin di backup. Untuk teks yang dipublikasikan, masalah ini tidak relevan. Untuk pekerjaan draft, arsitektur penting. Alat ini menjalankan seluruh pipeline di browser Anda melalui JavaScript dan marked.js. Markdown tidak pernah melintasi jaringan, verifikasi di tab Network DevTools saat Anda mengetik, atau bawa halaman offline (mode pesawat) setelah dimuat dan konfirmasi konverter masih bekerja. Aman untuk draft rahasia, deliverable klien, bab manuskrip di bawah NDA, memo internal atau hal lain yang tidak ingin Anda salin ke hard drive orang asing.

Pertanyaan yang Sering Diajukan

Dialek Markdown apa yang didukung konverter ini?

CommonMark dengan ekstensi GFM paling umum diaktifkan, tabel (pipe-delimited dengan alignment : opsional), blok kode fenced dengan petunjuk bahasa, strikethrough melalui ~~text~~, autolinks untuk URL telanjang, dan item task list melalui [ ] dan [x]. Heading, tebal, miring, tautan, gambar, daftar, blockquote, aturan horizontal dan kode inline semua berfungsi seperti yang Anda harapkan di GitHub. Renderer adalah marked.js, parser yang sama yang digunakan Markdown Previewer.

Apakah ini mendukung GitHub Flavored Markdown (GFM)?

Ya, tabel dengan pipe, blok kode fenced dengan petunjuk bahasa, daftar task, autolinks dan strikethrough semua berfungsi. Jika ekstensi GFM tidak dirender, periksa ulang input mengikuti aturan sintaks CommonMark/GFM: baris kosong di sekitar elemen blok, jumlah backtick yang cocok pada blok kode fenced, tepat dua spasi trailing (atau backslash) untuk hard line break. Penyebab paling umum dari "GFM tidak berfungsi" adalah editor yang menghapus whitespace trailing saat menyimpan, yang membunuh sintaks hard-break.

Akankah output terlihat sama di GitHub?

HTML struktural, paragraf, daftar, tabel, heading, akan cocok untuk input apa pun yang merupakan CommonMark + GFM yang valid. Dua lapisan akan berbeda. GitHub menerapkan tema CSS sendiri dan syntax-highlighting, jadi warna, font dan spasi akan terlihat berbeda. GitHub juga melapisi pasca-pemrosesan di atas spec, shortcode emoji (:smile:), mention @user, auto-linking #issue, jalur gambar relatif repositori, yang tidak direproduksi konverter yang sesuai spec. HTML yang dikeluarkan alat ini portabel secara struktural; tampilan visual tergantung pada CSS di tujuan.

Haruskah saya membersihkan output sebelum mempublikasikan?

Jika sumber dapat mencakup konten yang disediakan pengguna, ya. Parser Markdown melewatkan HTML mentah tanpa perubahan, jadi sumber yang berisi <img src=x onerror="alert(1)"> akan menghasilkan tag itu di output. Untuk sistem multi-pengguna, jalankan output melalui DOMPurify (Cure53, Februari 2014, sanitizer JavaScript de-facto) sebelum menyuntikkan ke DOM. Untuk penggunaan pribadi sekali pakai di mana sumber adalah tulisan Anda sendiri, ini bukan masalah, yang terburuk yang dapat Anda lakukan ke halaman Anda sendiri adalah menempelkan HTML Anda sendiri.

Bisakah saya mendapatkan dokumen HTML lengkap dengan head dan body?

Saat ini alat ini mengeluarkan hanya fragmen body, Markdown yang dikonversi dibungkus dalam tag HTML semantik tetapi tidak dalam dokumen <html>/<head>/<body> lengkap. Untuk menyimpan sebagai file .html standalone, bungkus output sendiri: <!DOCTYPE html><html><head><meta charset="utf-8"><title>...</title></head><body>[fragment]</body></html>. Atau gunakan Pandoc dengan flag --standalone untuk output sepenuhnya standalone dengan CSS yang didorong template.

Apakah Markdown saya dikirim ke mana pun?

Tidak. Konversi berjalan sepenuhnya di browser Anda melalui marked.js. Markdown yang Anda tempel tidak pernah melintasi jaringan, verifikasi di tab Network DevTools saat Anda mengetik, atau bawa halaman offline (mode pesawat) setelah dimuat dan konfirmasi konverter masih bekerja. Aman untuk draft rahasia, deliverable klien di bawah NDA, bab manuskrip atau teks apa pun yang tidak ingin Anda salin ke hard drive orang asing.

Alat terkait