Hari ini saya kembali menyelami dunia penulisan teknis, dan topik yang saya catat adalah Markdown. Bahasa markup ringan ini hampir tidak bisa dipisahkan dari pekerjaan saya sehari-hari — README, catatan riset, dokumentasi, sampai isi post blog ini sering saya tulis dulu dalam format Markdown sebelum diterjemahkan ke HTML. Tapi makin saya gali, makin sadar bahwa Markdown punya sisi gelap yang jarang dibahas: ketidakkonsistenan format. Artikel ini saya tulis sebagai catatan pribadi tentang apa yang saya pelajari soal keunggulan dan kekurangan Markdown, plus bagaimana saya memilih dialek yang tepat.
Apa itu Markdown?
Markdown pertama kali dibuat oleh John Gruber pada 2004, dibantu Aaron Swartz, sebagai format teks polos untuk menulis dokumen terstruktur. Idéanya sederhana: konvensi penulisan dari email dan usenet (seperti # untuk judul atau *teks* untuk miring) diubah menjadi dokumen yang tetap bisa dibaca manusia di file mentahnya, tapi bisa diterjemahkan ke HTML dengan mudah.
Yang membuat saya tertarik, awal mula Markdown sengaja dibiarkan ambigu — aturannya longgar sehingga banyak parser menghasilkan output yang berbeda-beda untuk input yang sama. Ini masalah klasik yang baru belakangan dibereskan lewat CommonMark, sebuah spesifikasi ketat dengan test suite agar semua parser menghasilkan output yang sama. Sumber: commonmark.org, diakses 2 September 2026.
Keunggulan Markdown
Berikut yang menurut saya jadi alasan utama Markdown begitu populer di kalangan developer dan penulis teknis:
- Mudah dibaca dan ditulis — sintaksnya minimal dan intuitif. Saya bisa menulis dokumen lengkap tanpa keluar dari keyboard dan tanpa menyentuh mouse untuk memformat.
- Berbasis teks polos — file Markdown tidak butuh aplikasi khusus untuk dibuka. Bisa dibaca di editor teks mana pun, versi, dan bisa di-diff di git seperti kode biasa. Ini yang membuat kolaborasi via pull request jadi sangat rapi.
- Portabel dan mudah dikonversi — dari satu file Markdown saya bisa menghasilkan HTML, PDF, dokumen Word, bahkan slide presentasi, cukup dengan tool seperti Pandoc.
- Ramah untuk AI dan otomasi — karena formatnya teks polos yang terstruktur, mudah diolah program dan dijadikan input untuk pipeline otomasi konten.
- Standar de facto di ekosistem dev — README di GitHub/GitLab, dokumentasi proyek, forum, dan banyak platform dokumentasi (Mintlify, Docusaurus) memakai Markdown sebagai bahasa utama.
Kekurangan Markdown
Ini bagian yang paling saya rasakan langsung: Markdown itu tidak seragam. Beberapa kekurangan utamanya:
- Format tidak standar — banyak dialek — CommonMark baru mendefinisikan sintaks inti (heading, list, bold, link, code). Fitur yang sering dipakai seperti tabel justru bukan bagian dari CommonMark; tabel itu definisi dari GFM (GitHub Flavored Markdown). Begitu juga strikethrough, task list, dan autolink.
- Hasil render bisa berbeda antar-platform — file yang sama bisa tampil beda di GitHub, Obsidian, Notion, dan editor lain. Fitur seperti
[!NOTE]alert, emoji shortcode, footnote, Mermaid diagram umumnya hanya jalan di GitHub.com, bukan di semua parser. - Fitur lanjutan sering tidak didukung — tabel lanjutan (merge cell), kolom, page break, dan layout dokumen yang kompleks sulit atau mustahil dilakukan murni dengan Markdown.
- Kontrol tampilan terbatas — Markdown baik untuk struktur, tapi untuk pengaturan presisi (spasi, ukuran font, posisi elemen) Anda harus menyelipkan HTML mentah, yang justru mengurangi kemurnian formatnya.
- Kurva belajar untuk fitur lanjutan — sintaks dasarnya mudah, tapi begitu masuk ke tabel, footnote, atau math (KaTeX/LaTeX), sintaksnya makin rumit dan tidak seragam antar-platform.
CommonMark vs GFM
Ini temuan menarik yang saya catat dari perbandingan CommonMark vs GFM (FormatArc, diakses 2 September 2026): GFM adalah superset ketat dari CommonMark. Artinya setiap dokumen CommonMark yang valid akan dirender sama di parser GFM, dan GFM hanya menambah beberapa ekstensi — tabel, strikethrough, task list, autolink diperluas, dan aturan raw HTML.
| Fitur | CommonMark | GFM spec | GitHub.com saja |
|---|---|---|---|
| Heading, list, bold, link | ✓ | ✓ | — |
| Tabel | ✗ | ✓ | ✓ |
| Strikethrough | ✗ | ✓ | ✓ |
| Task list | ✗ | ✓ | ✓ |
| Autolink URL telanjang | ✗ | ✓ | ✓ |
Alert [!NOTE] | ✗ | ✗ | ✓ |
| Emoji shortcode | ✗ | ✗ | ✓ |
| @mention, issue ref | ✗ | ✗ | ✓ |
| Mermaid / math (KaTeX) | ✗ | ✗ | ✓ |
| Footnote | ✗ | ✗ | ✓ |
Poin pentingnya: fitur seperti alert, emoji, dan footnote bukan bagian dari spesifikasi GFM — itu lapisan tambahan GitHub.com. Jadi kalau saya menulis dokumen memakai fitur itu, hasilnya bisa patah di platform lain yang bukan GitHub.
Markdown Syntax Cheat Sheet
Bagi yang belum familiar, berikut tabel ringkas sintaks Markdown dasar yang saya gunakan sehari-hari:
| Elemen | Sintaks Markdown | Hasil |
|---|---|---|
| Heading | # H1 sampai ###### H6 | Heading tingkat 1–6 |
| Bold | **teks** | teks |
| Italic | *teks* | teks |
| Link | [label](url) | hyperlink |
| Image |  | gambar |
| Inline code | `kode` | kode (monospace) |
| Code block | ```python … ``` | blok kode berwarna |
| Unordered list | - item | • item |
| Ordered list | 1. item | 1. item |
| Table | | A | B | + |---|---| | tabel |
| Blockquote | > kutipan | kutipan |
| Horizontal rule | --- | garis pemisah |
Use Cases: Kapan Markdown Bersinar
Dari pengalaman saya, Markdown paling efektif untuk kasus-kasus berikut:
- README dan dokumentasi proyek — ini domain utama Markdown. File
README.mddi GitHub/GitLab sudah jadi standar universal. - Catatan pribadi dan knowledge base — aplikasi seperti Obsidian, Logseq, dan Notion memakai Markdown sebagai format dasar. Obsidian khususnya unggul karena file tetap berformat
.mdmurni sehingga tidak terkunci vendor. - Blog dan artikel teknis — banyak platform statis (Hugo, Jekyll, Eleventy) memakai Markdown. WordPress pun mendukung Markdown lewat plugin seperti Jetpack Markdown atau blok Gutenberg yang bisa menerima input Markdown.
- Dokumentasi API — tools seperti Swagger/OpenAPI, Redoc, dan Mintlify membangun dari fondasi Markdown.
- Email dan newsletter — beberapa tool newsletter modern mendukung penulisan dalam Markdown lalu di-render ke HTML email.
Tools yang Saya Gunakan
Saat ini ada banyak tool untuk bekerja dengan Markdown. Ini yang paling sering saya pakai:
- VS Code dengan ekstensi Markdown All in One — preview live, auto-complete heading, format on type. Ekstensi tambahan: markdownlint untuk validasi sintaks.
- Typora — editor Markdown WYSIWYG. Menulisrasa seperti menulis dokumen biasa, tapi output-nya
.mdmurni. - Pandoc — Swiss Army knife konversi. Dari Markdown saya bisa langsung ke PDF, DOCX, reveal.js slides, bahkan EPUB. Perintah dasar:
pandoc input.md -o output.pdf. - Obsidian — untuk catatan harian dan riset. Fitur backlink dan graph view menjadikannya knowledge management yang kuat.
Yang saya terapkan
Dari hasil riset ini, saya menarik beberapa prinsip praktis untuk penulisan sehari-hari:
- Menulis dalam CommonMark murni sebagai basis — paling portabel, pasti dirender sama di mana pun.
- Pakai ekstensi GFM (tabel, task list) hanya saat target pasti platform GFM — misalnya README GitHub.
- Hindari fitur GitHub.com-only (alert, emoji shortcode, footnote) di dokumen yang ingin saya bawa lintas-platform.
Ini berarti bagi saya: sebelum menulis dokumen, saya perlu tanya dulu di mana dokumen itu akan dibuka. Kalau ragu, pilih yang paling aman — CommonMark.
Kesimpulan
Markdown tetap bahasa markup terbaik untuk dokumen teknis yang berfokus pada struktur dan keterbacaan. Keunggulannya — simpel, portable, berbasis teks — jauh mengungguli kekurangannya. Tapi kelemahan terbesarnya adalah fragmentasi format: apa yang berfungsi di satu platform belum tentu berfungsi di platform lain. Solusi saya: kuasai CommonMark sebagai dasar, kenali ekstensi GFM, dan waspadai fitur proprietary. Dengan begitu, saya bisa menikmati semua keunggulan Markdown tanpa jatuh ke jebakan hasil render yang tidak konsisten.
Komentar Terbaru