Markdown sedang menghambat Anda

 (newsletter.bphogan.com)
10 poin oleh GN⁺ 2025-11-24 | 7 komentar | Bagikan ke WhatsApp
  • Markdown, yang banyak digunakan untuk menulis dokumentasi pengembangan, populer berkat kesederhanaan dan aksesibilitasnya, tetapi memiliki keterbatasan untuk dokumentasi teknis berskala besar karena kurangnya daya ekspresi struktural
  • Markdown bekerja seperti sistem tipe implisit, sehingga konsistensi maupun validasi skema tidak dimungkinkan, dan juga ada masalah kompatibilitas di antara berbagai varian Markdown (flavor)
  • Sintaks ekstensi seperti MDX meningkatkan daya ekspresi, tetapi justru menambah kompleksitas karena portabilitas dan standardisasi antar sistem yang kurang
  • reStructuredText, AsciiDoc, DocBook, DITA dan lainnya menyediakan struktur eksplisit serta semantic markup yang memperkuat kemudahan penggunaan ulang dan keterbacaan oleh mesin
  • Untuk dokumen kecil, Markdown sudah memadai, tetapi untuk pengelolaan dokumentasi berskala besar dan multikanal, diperlukan peralihan ke format yang terstruktur

Keterbatasan struktural Markdown

  • Markdown memiliki sintaks sederhana yang mudah dibaca manusia, sehingga dapat membuat dokumen yang enak dilihat di GitHub atau situs statis
    • Namun, ia tidak dapat menjelaskan makna konten sehingga kekurangan informasi struktur yang dapat dipahami mesin
  • Mesin pencari, LLM, IDE, agen AI, dan lainnya memanfaatkan struktur semantik dokumen, tetapi Markdown hanya menghasilkan tag HTML yang terbatas
  • Markdown menimbulkan masalah inkonsistensi saat penggunaan ulang atau integrasi konten karena perbedaan sintaks antar platform
  • Akibatnya, Markdown pada dasarnya adalah format pada tingkat penyebut bersama terendah, sehingga tidak cocok untuk pengelolaan dokumen yang kompleks

Masalah tipe implisit pada Markdown

  • Markdown adalah format tanpa skema eksplisit atau definisi tipe, sehingga judul atau daftar yang sama bisa memiliki makna berbeda tergantung konteks
  • Ada berbagai varian Markdown (flavor), sehingga muncul perbedaan rendering antar alat
    • Contoh: beberapa alat mendukung catatan kaki, sementara alat lain mengabaikannya
  • MDX memperluas daya ekspresi dengan menyisipkan komponen React, tetapi portabilitasnya rendah karena masalah kompatibilitas antar sistem
  • Ekstensi seperti ini adalah upaya untuk menutupi keterbatasan Markdown, tetapi pada akhirnya hanya solusi sementara yang tidak terstandarisasi
Iklan

Pentingnya semantic markup

  • Semantic markup menjelaskan makna konten, bukan bentuknya
    • Contoh: “langkah (step)” dan “item daftar” bisa terlihat sama secara visual, tetapi maknanya berbeda
  • HTML5 memperkuat representasi struktural dengan memperkenalkan tag berbasis makna seperti <section>, <article>, <aside>
  • Keunggulan utama semantic markup
    • Transformasi dan penggunaan ulang: konten yang sama dapat diubah ke berbagai format seperti HTML, PDF, dan ePub
    • Keterbacaan oleh mesin: LLM atau agen dapat mengenali struktur dengan jelas dan memberikan respons yang lebih akurat
  • Karena Markdown tidak menyediakan informasi struktur semacam ini, terjadi kehilangan informasi saat pascapemrosesan atau konversi

Perbandingan format alternatif

  • reStructuredText
    • Format yang digunakan di Sphinx dalam ekosistem Python, mengekspresikan makna struktural melalui directive dan role
    • Mendukung elemen struktur eksplisit seperti blok kode, catatan (note), dan referensi silang (:ref:)
    • Cocok untuk dokumentasi teknis berskala besar dan mendukung pembuatan HTML serta PDF
  • AsciiDoc
    • Format teks semantik yang menyediakan attribute, konten kondisional, dan fitur include
    • Mendukung ekspresi yang dioptimalkan untuk dokumentasi teknis seperti NOTE, WARNING, elemen UI, dan penulisan pintasan keyboard
    • Dapat dikonversi ke HTML, PDF, ePub, DocBook, dan lainnya melalui AsciiDoctor
    Iklan
  • DocBook (XML)
    • Model berbasis XML untuk publikasi teknis yang menyediakan sistem tag bermakna seperti <command>, <note>, <xref>
    • Mencakup tag yang dibutuhkan untuk dokumen profesional seperti glosarium, indeks, elemen UI, dan nama fungsi
    • Dapat dikonversi ke berbagai format keluaran melalui stylesheet XSLT
    • Menguntungkan untuk validasi struktur dokumentasi berskala besar dan pembuatan indeks
  • DITA (Darwin Information Typing Architecture)
    • Struktur modular berbasis XML yang digunakan sebagai standar dokumentasi teknis perusahaan
    • Arsitektur XML berbasis topik yang mendefinisikan dengan jelas struktur prosedural seperti <task>, <step>
    • Digunakan sebagai standar pengelolaan dokumentasi perusahaan untuk penggunaan ulang konten (conref), pemfilteran, dan penerbitan multikanal
    • Mendukung otomatisasi rendering dan konversi melalui DITA Open Toolkit

Mengapa XML tetap diperlukan meski terlihat merepotkan

  • Markdown memang ringan, tetapi merupakan solusi sementara yang tidak memiliki struktur, standar, dan konsistensi
  • Jika Anda menambah kompleksitas pada Markdown dengan MDX, plugin, dan skrip kustom,
    mengadopsi format terstruktur secara langsung akan lebih stabil dalam jangka panjang

Jadi, apa yang sebaiknya dilakukan?

  • Untuk dokumen kecil seperti README atau dokumen sekali pakai, Markdown sudah cukup, tetapi
    untuk dokumentasi berskala besar, dapat digunakan ulang, dan multikanal, reStructuredText, AsciiDoc, DocBook, dan DITA lebih cocok
  • Jika Anda membutuhkan dokumen perencanaan, dokumentasi pengembang, penggunaan ulang, dan pengelolaan skala besar, pertimbangkan reST/AsciiDoc lalu DocBook/DITA
  • Pendekatan yang ideal adalah menggunakan format dengan struktur paling kaya sebagai sumber, lalu mengonversinya ke Markdown bila perlu
  • Markdown berguna sebagai format keluaran, tetapi jika digunakan sebagai sumber utama (source of truth), perluasan struktural akan sulit
  • Yang optimal adalah menyimpan sumber dalam format dengan struktur makna yang kaya, dan menggunakan Markdown sebagai keluaran downstream

Bacaan terkait

7 komentar

 
savvykang 2025-11-24

Realitas format berbasis XML dan kriteria pemilihannya
Untuk dokumen kecil seperti README atau dokumen sekali pakai, Markdown sudah memadai,
namun untuk dokumen berskala besar, dapat digunakan ulang, dan multikanal, reStructuredText, AsciiDoc, DocBook, dan DITA lebih cocok

Apakah rst itu format berbasis XML? Baru kali ini saya dengar. Ringkasannya aneh.
 
xguru 2025-11-24

Sepertinya judulnya ditulis seperti itu karena dalam ringkasan dibahas kriteria pemilihan sambil mengelompokkannya bersama format XML lainnya.
Saya sudah memperbaikinya agar sesuai dengan teks aslinya.
 
jjw9512151 2025-11-24

Kalau perlu di Markdown pakai html lalu tempelkan mermaid di situ, kurang lebih jadi sih.. selebihnya rasanya malah jadi pekerjaan membuat dokumen demi pekerjaan dokumentasi itu sendiri
 
ahwjdekf 2025-11-24

Manusia lebih dulu daripada AI. Jangan mencuri apa yang kutulis. Ngomong apa soal semantik.
 
slowandsnow 2025-11-24

Kalau harus memakai sintaks khusus, akan muncul kurva belajar baru lagi, alat parsing khusus, viewer, editor, dan semuanya harus didukung dengan lancar agar bisa dipakai.. kalau sudah sampai segitu, mungkin lebih baik pakai Google Docs atau Notion saja yang bisa terhubung dengan lancar ke sebagian besar layanan AI
 
GN⁺ 2025-11-24
Pendapat Hacker News

  • Inti dari Markdown adalah dukungan yang sangat luas yang tidak dimiliki bahasa lain Sebagian besar alternatif memerlukan alat terpisah, dan tidak bisa dipakai di lingkungan yang sudah mendukung Markdown Bahkan Google Docs mendukung paste Markdown sebagai fitur tersembunyi Meski tidak sempurna, keunggulannya adalah bisa dipakai “di mana saja” Seperti HTML yang lebih sederhana daripada SGML namun menjadi standar karena didukung browser, Markdown juga bisa berkembang seiring waktu Ambiguitas standardisasi, kekurangan fitur, dan masalah kompatibilitas mirip dengan situasi HTML4 dulu Menurut saya, evolusi bertahap lebih realistis daripada menggantinya sepenuhnya

    • Kelebihan lain Markdown adalah siapa pun bisa mempelajarinya dalam 5 menit Dulu pernah diterapkan untuk para jurnalis surat kabar, dan dalam sehari mereka merasa ini lebih nyaman daripada MS Word Daya tariknya adalah hasil keluar sesuai yang diketik tanpa pemformatan rumit Ini format yang mudah dipelajari bahkan oleh orang nonteknis
    • Saya rasa Markdown sudah menjadi pemenang de facto Jika klien menginginkan Word atau PDF, saya kirim seperti itu, tetapi pada akhirnya penerimalah yang menentukan format Untuk code block, backtick sudah cukup, dan tabel atau diagram yang rumit bisa dilengkapi dengan HTML
    • Karakteristik penting Markdown adalah mudah dibaca bahkan sebagai teks polos Jauh lebih mudah dibaca daripada LaTeX atau HTML Saya menganggapnya sebagai bahasa markup tingkat tinggi yang dikompilasi ke HTML Jika perlu, kita juga bisa langsung mencampurkan HTML
    • Memang benar Markdown dipakai luas, tetapi tidak ada alasan teknis yang menghalangi bahasa lain Hanya saja perluasannya lambat karena faktor sosial Tidak ada tata bahasa yang sistematis seperti HTML, jadi sulit untuk diperluas Sudah ada banyak dialek Markdown, tetapi kebanyakan terbatas pada sedikit alat saja CommonMark adalah yang paling mendekati standar Bahkan jika sistem ekstensi diperkenalkan, saya rasa peluang suksesnya rendah karena masalah benturan sintaks
    • Markdown mungkin bisa berkembang, tetapi tidak ada otoritas pusat CommonMark memang ada, tetapi lebih merupakan penjelasan teknis daripada standar normatif

  • Markdown bisa menyertakan tag HTML di mana saja Ini juga dinyatakan di dokumentasi resmi Jadi batasan yang disebut penulis sebenarnya tidak ada

    • Semua orang tahu bahwa HTML bisa disisipkan Tapi alasan memakai Markdown adalah agar tidak perlu menulis HTML secara langsung Jika tetap harus terus menulis tag seperti atau, tidak ada alasan memakai Markdown Jika jawabannya pada akhirnya “pakai saja HTML”, maka alasan keberadaan Markdown hilang
    • Dalam praktiknya, HTML dan Markdown tidak bisa dicampur dengan bebas Saat blok HTML masuk, sintaks Markdown dinonaktifkan AsciiDoc jauh lebih fleksibel dalam hal ini
    • Saya juga memakai Pandoc dan Markdown, tetapi tidak berniat kembali ke AsciiDoc atau LaTeX Catatan kaki dan daftar isi juga umumnya didukung, dan untuk pekerjaan berbasis teks biasa ini sudah cukup Saya tidak butuh hal seperti rumus atau tombol
    • Ada juga platform seperti Reddit atau GitHub yang memblokir HTML demi keamanan Karena berbahaya jika pengguna yang tidak tepercaya bisa memakai HTML
    • Saya juga kadang menambahkan elemen interaktif ke dalam dokumen Markdown Saat ini saya hanya memakai Markdown untuk penulisan konten

  • Saat kuliah mengambil jurusan fisika, saya menulis makalah dengan LaTeX Jurusan kimia memakai Word, jadi standarnya berbeda-beda menurut bidang Nomor versi TeX mengekspresikan tingkat kelengkapan targetnya dengan mendekati nilai π Versi saat ini adalah 3.141592653, dan telah dipertahankan stabil selama 47 tahun Lihat wiki TeX, penjelasan versi Pi Untuk alat CLI, format manpage juga berguna

    • Saat S1 saya belajar menulis dokumen dengan LaTeX, tetapi sekarang saya lebih merekomendasikan Typst Menurut saya ini kandidat penerus LaTeX yang paling menjanjikan
    • Menulis dokumen harus punya gesekan serendah mungkin LaTeX punya hambatan masuk yang tinggi, dan tidak efisien karena lebih merupakan format typesetting daripada format dokumen Dokumen seharusnya lebih berfokus pada isi daripada tampilan luar
    • Saya satu-satunya yang menulis makalah dengan Word Saya sempat kesulitan karena memakai font LaTeX dan memperbaiki bug PDF, tapi hasilnya baik-baik saja Menurut penelitian, pengguna LaTeX menghabiskan lebih banyak waktu tetapi kepuasan terhadap prosesnya lebih tinggi Rasanya seperti alat untuk “orang-orang yang menikmati proses membuatnya”

  • Markdown itu seperti produk minimum yang layak (MVP) Mudah dipelajari, dan tetap mudah dibaca meski belum dirender Untuk membuat PDF saya pindah dari AsciiDoc ke Typst, yang menyelesaikan masalah aksesibilitas Tetapi bahasa markup apa pun tidak akan otomatis meningkatkan kualitas tulisan Mengganti pena tidak membuat tulisan jadi lebih baik

    • Menurut saya penulis mencampuradukkan dua kegunaan Markdown ditujukan bagi orang yang ingin membuat konten dengan cepat Ini tidak cocok bagi mereka yang mengejar kesempurnaan struktural Saya rasa tidak akan ada bahasa yang bisa memuaskan kedua tujuan sekaligus
    • Alternatif Markdown bernama Djot juga menarik Lihat tautan GitHub
    • LaTeX membuat kita menambahkan komentar per paragraf sehingga mendorong pemikiran yang lebih mendalam tentang tulisan
    • Typst tampak menarik, tetapi saat ini hanya ada editor web dan plugin VSCode sehingga ekosistemnya masih terbatas

  • Nada tulisan ini adalah klaim bahwa “Markdown menghambat perkembangan LLM” Tetapi asumsi bahwa kekayaan semantik bisa diperoleh secara otomatis itu tidak realistis Di dalam tim, kami juga tidak punya waktu untuk pekerjaan seperti itu, dan Markdown sudah cukup Seperti diskusi tentang semantic web, pada akhirnya ini soal siapa yang mengelola datanya

  • Saya menulis blog dengan Org-mode + Emacs Yang paling saya suka adalah kemampuan menghubungkan code block dan menjalankannya di dalam dokumen Saya juga pernah memakai platform seperti Blorgit dan lazyblorg, tetapi konfigurasinya merepotkan jadi saya ekspor langsung ke HTML dan mengunggahnya ke server dengan rsync Saya menambahkan indeks dengan skrip Ruby lalu mendistribusikannya Ini jauh lebih ekspresif dan alami daripada Markdown

    • Seandainya Org-mode tidak terikat pada Emacs, rasanya ini bisa menjadi format default
    • Saya ingin bertanya apakah pernah mencoba Ox-Hugo Ini sistem yang hebat untuk mengekspor file Org ke blog Hugo
    • Org-mode terlalu melekat dengan Emacs sehingga sulit dipindahkan Jika ada LSP, sepertinya ini bisa dipakai juga di lingkungan lain

  • Saya sebagian setuju dengan klaim bahwa “Markdown kurang struktur”, tetapi saya kurang suka pendekatan yang terlalu dikotomis Sebelum memilih format, seharusnya kebutuhan strukturnya dipahami dulu Karena itu saya agak tidak nyaman, tetapi juga sulit untuk sepakat sepenuhnya

  • Menyodorkan DITA sebagai alternatif Markdown adalah klaim yang sangat meleset DITA adalah sistem XML perusahaan berskala besar, dan tujuannya sama sekali berbeda dari Markdown Ini hanya cocok di lingkungan seperti organisasi dengan lebih dari 5.000 orang atau lini produk multibahasa Jika situasinya cocok memakai Markdown, DITA jelas tidak cocok Keduanya sama-sama buang waktu

    • Saya tidak tahu DITA sebelumnya, tetapi kalimat “kalau Markdown terlalu rumit, pakailah XML” terasa sangat lucu
    • Saya ingin mendengar lebih banyak tentang DITA dan contoh kegagalan toolchain-nya

  • Saya sudah memakai Markdown lebih dari 10 tahun dan masih berfungsi dengan baik Klaim dalam tulisan itu juga tidak sepenuhnya salah, tetapi ini bukan masalah yang dirasakan pengguna Markdown Kalau perlu, pakai saja yang lain Meski begitu, judulnya bagus jadi saya membacanya sekitar 5 menit

  • Agak aneh menyebut MyST sebagai salah satu bentuk Markdown, lalu kembali memberi contoh reStructuredText (rST) Padahal tujuan MyST memang sebagai pengganti rST Sintaksnya bergaya Markdown, tetapi tetap mendukung makna struktural, directive, role, dan sebagainya Ada juga diskusi terkait di isu Sphinx
 
mstorm 2025-11-24

Akhir-akhir ini tulisan seperti ini sering terlihat.

File teks, Markdown, format yang lebih terstruktur
Seiring perubahannya, tidak ada satu jawaban yang mutlak; cukup gunakan format yang tepat pada saat yang tepat.

Dan karena masalah akan muncul jika selalu berusaha melakukan semuanya dalam satu file, pada akhirnya kita memang perlu mengelompokkan dan menatanya secara sistematis sesuai topiknya.