Markdown sizi geride tutuyor

 (newsletter.bphogan.com)
10 puan yazan GN⁺ 2025-11-24 | 7 yorum | WhatsApp'ta paylaş
  • Geliştirici dokümantasyonu yazımında yaygın biçimde kullanılan Markdown, sadeliği ve erişilebilirliği sayesinde popüler olsa da, yapısal ifade gücünün yetersizliği nedeniyle büyük ölçekli teknik dokümanlarda sınırlamalara sahiptir
  • Markdown, örtük bir tip sistemi gibi çalışır; bu yüzden tutarlılık ya da şema doğrulaması mümkün değildir ve farklı Markdown türevleri (flavor) arasında uyumluluk sorunları da bulunur
  • MDX gibi genişletilmiş sözdizimleri ifade gücünü artırsa da, sistemler arasında taşınabilirlik ve standardizasyon eksikliği nedeniyle aksine karmaşıklığı artırır
  • reStructuredText, AsciiDoc, DocBook, DITA gibi alternatifler açık yapı ve anlamsal işaretleme (semantic markup) sunarak yeniden kullanılabilirliği ve makine tarafından yorumlanabilirliği güçlendirir
  • Küçük ölçekli dokümanlar için Markdown yeterli olsa da, büyük ölçekli ve çok kanallı doküman yönetimi için yapılandırılmış biçimlere geçiş gereklidir

Markdown'ın yapısal sınırları

  • Markdown, insanın kolay okuyabildiği basit bir sözdizimiyle GitHub ya da statik sitelerde iyi görünen dokümanlar üretmeyi sağlar
    • Ancak içeriğin anlamını tarif edemediği için makinenin anlayabileceği yapısal bilgi yetersiz kalır
  • Arama motorları, LLM'ler, IDE'ler ve yapay zeka ajanları dokümanın anlamsal yapısından yararlanır; ancak Markdown yalnızca sınırlı HTML etiketleri üretir
  • Markdown, platforma göre değişen sözdizimi farkları nedeniyle yeniden kullanımda ya da içerik birleştirmede tutarsızlık sorunları yaratır
  • Sonuç olarak Markdown, en düşük ortak payda düzeyinde bir biçimdir ve karmaşık doküman yönetimi için uygun değildir

Markdown'ın örtük tip sorunu

  • Markdown, açık bir şema ya da tip tanımı olmayan bir biçimdir; bu nedenle aynı başlık ya da liste bağlama göre farklı anlamlar taşıyabilir
  • Birçok Markdown türevi (flavor) bulunduğundan, araçlar arasında render farkları oluşur
    • Örneğin bazı araçlar dipnotları desteklerken, diğerleri bunları yok sayar
  • MDX, React bileşenleri ekleyerek ifade gücünü genişletir; ancak sistemler arası uyumluluk sorunları nedeniyle taşınabilirliği düşüktür
  • Bu tür genişletmeler Markdown'ın sınırlarını aşma çabası olsa da, standartlaşmamış geçici çözümlerden öteye gitmez
Reklam

Anlamsal işaretlemenin önemi

  • Anlamsal işaretleme, içeriğin biçimini değil anlamını tanımlar
    • Örneğin “adım (step)” ile “liste öğesi” görsel olarak aynı olsa da anlam olarak farklıdır
  • HTML5, <section>, <article>, <aside> gibi anlam temelli etiketler ekleyerek yapısal ifadeyi güçlendirmiştir
  • Anlamsal işaretlemenin temel avantajları
    • Dönüştürme ve yeniden kullanım: Aynı içerik HTML, PDF, ePub gibi farklı biçimlere dönüştürülebilir
    • Makine tarafından yorumlanabilirlik: LLM'ler ya da ajanlar yapıyı açık biçimde algılayarak daha doğru yanıtlar verebilir
  • Markdown bu tür yapısal bilgileri sağlayamadığı için, son işlem ya da dönüşüm sırasında bilgi kaybı yaşanır

Alternatif biçimlerin karşılaştırması

  • reStructuredText
    • Python ekosistemindeki Sphinx'te kullanılan bir biçimdir; directive ve role yapılarıyla yapısal anlam ifade eder
    • Kod blokları, notlar (note), çapraz başvuru (:ref:) gibi açık yapısal öğeleri destekler
    • Büyük ölçekli teknik dokümanlar için uygundur ve HTML ile PDF üretimini destekler
  • AsciiDoc
    • attribute, koşullu içerik ve include özellikleri sunan bir anlamsal metin biçimidir
    • NOTE, WARNING gibi uyarılarla birlikte UI öğeleri, kısayol gösterimleri gibi teknik dokümantasyona özel ifadeleri destekler
    • AsciiDoctor ile HTML, PDF, ePub, DocBook gibi biçimlere dönüştürülebilir
    Reklam
  • DocBook (XML)
    • Teknik yayıncılık için XML tabanlı bir modeldir ve <command>, <note>, <xref> gibi anlam taşıyan etiket sistemleri sunar
    • Sözlükçe, dizin, UI öğeleri, fonksiyon adları gibi uzman dokümanlarda gerekli etiketleri içerir
    • XSLT stylesheet'leri aracılığıyla farklı çıktı biçimlerine dönüştürülebilir
    • Büyük ölçekli doküman yapısı doğrulaması ve indeks üretimi için avantajlıdır
  • DITA (Darwin Information Typing Architecture)
    • Kurumsal teknik dokümantasyon standardı olarak kullanılan modüler XML tabanlı bir yapıdır
    • Konu tabanlı XML mimarisi ile <task>, <step> gibi süreçsel yapıları açıkça tanımlar
    • İçerik yeniden kullanımı (conref), filtreleme, çok kanallı yayıncılık gibi alanlarda kurumsal doküman yönetimi standardı olarak kullanılır
    • DITA Open Toolkit ile render ve dönüşüm otomasyonu desteklenir

XML rahatsız edici görünse de neden gerekli?

  • Markdown hafiftir, ancak yapı, standart ve tutarlılıktan yoksun geçici bir çözümdür
  • Markdown'a MDX, eklentiler ve özel script'lerle karmaşıklık ekliyorsanız,
    uzun vadede doğrudan yapılandırılmış bir biçim benimsemek daha istikrarlıdır

Peki ne yapılmalı?

  • README ya da tek seferlik dokümanlar gibi küçük ölçekli belgeler için Markdown yeterlidir; ancak
    büyük ölçekli, yeniden kullanılabilir ve çok kanallı dokümantasyon için reStructuredText, AsciiDoc, DocBook ve DITA daha uygundur
  • Planlama dokümanları, geliştirici dokümanları, yeniden kullanım ve büyük ölçekli yönetim gerekiyorsa reST/AsciiDoc'tan başlayıp ardından DocBook/DITA değerlendirilebilir
  • En zengin yapısal özelliklere sahip biçimi kaynak olarak kullanıp, gerekirse Markdown'a dönüştürmek daha doğru bir yaklaşımdır
  • Markdown, çıktı biçimi olarak kullanışlıdır; ancak tek gerçek kaynak (source of truth) olarak kullanıldığında yapısal olarak genişlemesi zordur
  • En iyi yaklaşım, kaynağı anlamsal yapısı zengin bir biçimde tutup Markdown'ı aşağı akış çıktısı için kullanmaktır

İlgili okumalar

7 yorum

 
savvykang 2025-11-24

XML tabanlı formatların gerçekliği ve seçim ölçütleri
README ya da tek seferlik belgeler gibi küçük ölçekli dokümanlar için Markdown yeterli, ancak
büyük ölçekli, yeniden kullanılabilir ve çok kanallı dokümantasyon için reStructuredText, AsciiDoc, DocBook ve DITA daha uygundur.

rst XML tabanlı bir format mı? Bunu ilk kez duyuyorum. Özet tuhaf.
 
xguru 2025-11-24

Özet açısından diğer XML formatlarıyla birlikte değerlendirip seçim ölçütlerinden söz ederken başlığın o şekilde yazılmış gibi görünüyor.
Orijinal metne uygun olacak şekilde düzelttim.
 
jjw9512151 2025-11-24

Gerektiğinde Markdown içinde HTML kullanıp üstüne mermaid ekleyince aşağı yukarı oluyor.. ama onun ötesi, sanki belge için belge işi yapmaya dönüşüyor gibi
 
ahwjdekf 2025-11-24

Yapay zekadan önce insan gelir. Yazdığımı çalmayın. Semantik falan diyorsunuz.
 
slowandsnow 2025-11-24

Özel bir sözdizimi kullanılacaksa bunun için ayrıca bir öğrenme eğrisi oluşur; buna özel ayrıştırma araçları, görüntüleyici, editör vb. her şeyin de sorunsuz şekilde desteklenmesi gerekir.. O seviyedeyse, çoğu yapay zeka hizmetiyle sorunsuz bağlanabilen Google Docs ya da Notion kullanmak belki de daha iyidir
 
GN⁺ 2025-11-24
Hacker News görüşleri

  • Markdown’ın özü, diğer dillerde olmayan geniş destek görmesi Alternatiflerin çoğu ayrı araçlar gerektiriyor ve Markdown’ın zaten desteklendiği ortamlarda kullanılamıyor Hatta Google Docs bile gizli bir özellikle Markdown yapıştırmayı destekliyor Kusursuz olmasa da, avantajı “her yerde kullanılabilmesi” HTML, SGML’den daha basitti ama tarayıcılar destekleyince standart haline geldi; Markdown da zamanla gelişebilir Standardizasyondaki belirsizlik, özellik eksikliği ve uyumluluk sorunları HTML4 dönemine benziyor Tamamen değiştirmektense kademeli evrim daha gerçekçi bir yol gibi görünüyor

    • Markdown’ın bir başka avantajı da herkesin 5 dakikada öğrenebilmesi Eskiden bunu gazete muhabirlerine uygulamıştım; bir gün içinde MS Word’den daha rahat geldiğini düşündüler Karmaşık biçimlendirme olmadan, yazdığının aynısını sonuçta görmek cazipti Teknik olmayan kişiler için bile kolay öğrenilen bir format
    • Markdown’ın zaten fiilî kazanan olduğunu düşünüyorum Müşteri Word ya da PDF isterse öyle gönderirim ama sonuçta formatı alıcı belirler Kod blokları için backtick yeterli, karmaşık tablolar ya da diyagramlar için de HTML ile tamamlanabilir
    • Markdown’ın önemli bir özelliği, düz metin olarak da okunmasının kolay olması LaTeX ya da HTML’den çok daha okunaklı Bunu, HTML’ye derlenen üst düzey bir işaretleme dili olarak görüyorum Gerekirse doğrudan HTML de karıştırılabilir
    • Markdown’ın yaygın kullanıldığı doğru ama başka dilleri engelleyen teknik bir neden yok Yine de toplumsal etkenler yüzünden genişleme yavaş ilerliyor HTML gibi sistemli bir sözdizimi olmadığı için genişletmesi zor Zaten sayısız Markdown lehçesi var ama çoğu birkaç araçla sınırlı CommonMark en fazla standarda yaklaşanı Bir genişletme sistemi getirilse bile sözdizimi çakışmaları yüzünden başarılı olma ihtimali düşük görünüyor
    • Markdown gelişebilir ama merkezi bir otorite yok CommonMark var ama bu da norm koyan bir standarttan çok teknik açıklama düzeyinde

  • Markdown, her yerde HTML etiketleri içerebilir Resmî belgede de açıkça belirtiliyor Bu yüzden yazarın sözünü ettiği kısıt aslında yok

    • HTML eklenebildiğini herkes biliyor Ama Markdown kullanma nedeni zaten HTML’yi elle yazmamak Sürekli ya da gibi etiketler yazmak gerekecekse Markdown kullanmanın anlamı kalmaz Sonuçta cevap “HTML kullan” olacaksa Markdown’ın varlık nedeni ortadan kalkar
    • Pratikte HTML ile Markdown’ı özgürce karıştırmak mümkün değil HTML bloğu girince Markdown sözdizimi devre dışı kalıyor AsciiDoc bu konuda çok daha esnek
    • Ben de Pandoc ve Markdown kullanıyorum ama AsciiDoc ya da LaTeX’e dönmeyi düşünmüyorum Dipnotlar ya da içindekiler tablosu da çoğunlukla destekleniyor ve genel metin tabanlı işler için yeterli Denklem ya da buton gibi şeylere ihtiyaç duymuyorum
    • Reddit ya da GitHub gibi güvenlik nedeniyle HTML’yi engelleyen platformlar da var Çünkü güvenilmeyen kullanıcıların HTML yazması riskli olabilir
    • Ben bazen Markdown belgelerine etkileşimli öğeler de koyuyorum Şimdilik Markdown’ı yalnızca içerik yazımı için kullanıyorum

  • Üniversitede fizik okurken makalelerimi LaTeX ile yazdım Kimya bölümü Word kullanıyordu; yani standart alanlara göre değişiyor TeX’in sürüm numarası, hedeflenen tamamlanmışlık düzeyini π değerine yaklaşacak şekilde ifade ediyor Mevcut sürüm 3.141592653 ve 47 yıldır istikrarlı biçimde korunuyor TeX wiki, Pi sürüm açıklaması bakılabilir CLI araçları için manpage formatı da faydalı

    • Lisans yıllarımda LaTeX ile belge yazmayı öğrendim ama bugün Typst’i daha çok öneririm LaTeX’in halefi olmaya en yakın adayın o olduğunu düşünüyorum
    • Belge yazımında sürtünmenin az olması gerekir LaTeX’in giriş eşiği yüksek ve belge formatından çok dizgi formatı olduğu için verimsiz Belgelerde görünüşten çok içerik merkeze alınmalı
    • Makalesini Word ile yazan tek kişi bendim LaTeX fontları kullanmak ve PDF hatalarını düzeltmekle uğraştım ama idare etti Araştırmalara göre LaTeX kullanıcıları daha fazla zaman harcıyor ama süreçten aldıkları tatmin daha yüksek Biraz “bir şeyler üretmenin keyfini sevenlerin” aracı gibi

  • Markdown, minimum uygulanabilir ürün (MVP) gibi bir şey Öğrenmesi kolay ve render edilmemiş haliyle de okunaklı PDF üretimini AsciiDoc’tan Typst’e taşıdım; erişilebilirlik sorunlarını çözdü Ama hiçbir işaretleme dili yazının kalitesini kendi başına artırmaz Kalemi değiştirmek yazıyı daha iyi yapmaz

    • Bence yazar iki kullanım amacını karıştırmış Markdown, hızlıca içerik üretmek isteyenler için Yapısal bütünlük arayanlara uygun değil Her iki amacı birden karşılayan bir dil muhtemelen yoktur
    • Djot adlı Markdown alternatifi de ilginç GitHub bağlantısı bakılabilir
    • LaTeX, her paragraf hakkında not düşmeye zorladığı için yazı üzerine daha derin düşünmeyi sağlıyor
    • Typst ilginç görünüyor ama şu anda yalnızca web editörü ve VSCode eklentisi olduğu için ekosistemi sınırlı

  • Bu yazının tonu, “Markdown LLM gelişimini engelliyor” iddiası üzerine kurulu Ama anlamsal zenginliğin otomatik olarak elde edilebileceği varsayımı gerçekçi değil Ekip içinde böyle şeylere zaman yok ve Markdown yeterli geliyor Semantik web tartışmalarında olduğu gibi, mesele sonunda veriyi kimin yöneteceğine çıkıyor

  • Blogumu Org-mode + Emacs ile yazıyorum Kod bloklarını bağlayıp belge içinde çalıştırabilme özelliğini özellikle seviyorum Blorgit, lazyblorg gibi platformları da kullandım ama kurulum zahmetli olduğu için doğrudan HTML’ye aktarım yapıp rsync ile sunucuya yüklüyorum Ruby betiğiyle indeks ekleyip yayımlıyorum Markdown’dan çok daha ifade gücü yüksek ve doğal

    • Org-mode, Emacs’e bağlı olmasaydı varsayılan format haline gelmiş olabilirdi
    • Ox-Hugo denedin mi diye sormak isterim Org dosyalarını Hugo bloguna aktarmak için harika bir sistem
    • Org-mode, Emacs’e fazla sıkı bağlı olduğu için taşınması zor LSP gelirse başka ortamlarda da kullanılabilir gibi duruyor

  • “Markdown’ın yapısı yetersiz” iddiasına kısmen katılıyorum ama ikili karşıtlıkla yaklaşılması rahatsız edici Bir format seçmeden önce ihtiyaç duyulan yapının ne olduğunu anlamak gerekirdi Bu yüzden biraz sinir bozucu ve tam olarak katılmak zor

  • DITA’nın Markdown alternatifi olarak sunulması tam anlamıyla alakasız bir iddia DITA, büyük ölçekli kurumsal XML sistemidir; amacı Markdown’la tamamen farklı Ancak 5 binden fazla kişinin olduğu, çok dilli ürün hatları gibi ortamlarda uygundur Markdown kullanılan bir senaryoda DITA asla uygun olmaz İkisi de zaman kaybı

    • DITA’yı bilmiyordum ama “Markdown karmaşıksa XML kullan” demek aşırı komikti
    • DITA ve onun başarısız toolchain örnekleri hakkında daha fazlasını duymak isterim

  • Markdown’ı 10 yılı aşkın süredir kullanıyorum ve hâlâ gayet iyi çalışıyor Yazının iddiası tamamen yanlış değil ama Markdown kullanıcılarının hissettiği bir sorun da değil Gerekirse başka bir şey kullanılır Yine de başlığı güzel olduğu için 5 dakika kadar okudum

  • MyST’ten Markdown’ın bir türü diye söz edip ardından yeniden reStructuredText(rST) örneğini vermek tuhaf Oysa MyST’in amacı tam da rST’nin yerine geçmek Sözdizimi Markdown benzeri ama yapısal anlam, directive ve role gibi özelliklerin hepsini destekliyor Sphinx sorunu içinde de ilgili tartışma var
 
mstorm 2025-11-24

Bu aralar bu tür yazıları sıkça görüyorum.

Metin dosyaları, Markdown, daha yapılandırılmış formatlar...
Böyle değişirken tek bir doğru yok; doğru zamanda doğru formatı kullanmak yeterli.

Ayrıca her şeyi her zaman tek bir dosyada yapmaya çalışınca sorun çıkıyor; bu yüzden konuya göre sınıflandırmak ve sistematik hale getirmek kaçınılmaz.