Markdown ve HTML: hangisi ne zaman doğru seçimdir

Özet.Markdown, HTML’e derlenen yazar dostu bir kaynak formatıdır. HTML ise her tarayıcının, e-posta istemcisinin ve içerik yönetim sisteminin nihayetinde tükettiği işleme hedefidir. Düz metin yazarken Markdown kullanın; karmaşık düzenler, formlar ve etkileşimli öğeler için satır içi HTML’e geçin.

Markdown ve HTML çoğu zaman birbirinin alternatifi olarak tartışılır. Değillerdir. Markdown, HTML’e derlenen yazar dostu bir kaynak formatıdır. HTML ise tarayıcıların, e-posta istemcilerinin ve çoğu statik site oluşturucunun nihayetinde tükettiği evrensel belge işleme formatıdır. Soru hangisini seçeceğiniz değil — hangisinde yazacağınızdır.

Temel farklar

Markdown’ın üstün olduğu durumlar

• README dosyaları, belgeler, blog yazıları. Tam bu amaç için tasarlanmıştır. Yazarken okuma kolaylığı, etiket gürültüsü yok, sürüm kontrolü diff’leri temiz çalışır.
• Yorumlar, sorunlar, sohbet mesajları. GitHub, Discord, Slack ve modern her iş birliği aracı Markdown kabul eder. Kalın, bağlantılar, kod blokları, listeler — evrensel destek.
• Statik site oluşturucular. Hugo, Jekyll, Next.js MDX ve her modern blog motoru Markdown girişini kabul eder.
• Düz metnin baskın olduğu her yer. Markdown, “ara sıra biçimlendirmeli metin” için optimize edilmiştir — tam olarak yazarların ihtiyaç duyduğu oran.

HTML’in üstün olduğu durumlar

• Karmaşık düzenler. Çok sütunlu yapılar, hücre düzeyinde stillendirilmiş tablolar, özel konumlandırma. Markdown, CSS’in beklediğini ifade edemez.
• Üretim web sayfaları. Tarayıcı yalnızca HTML işler. Kaynağınız Markdown olsa bile yayınlanan sayfa HTML’dir.
• E-posta. Çoğu e-posta istemcisi HTML işler; çok azı doğrudan Markdown işler. Pazarlama e-postaları HTML + satır içi stiller kullanır çünkü e-posta istemcileri daha sofistike içerikleri bozar.
• Etkileşimli öğeler. Formlar, komut dosyaları, iframe’ler, erişilebilirlik nitelikleri (aria-*, role) — yalnızca HTML.

Lehçe sorunu

“Markdown” tek bir spesifikasyon değildir. Birbiriyle uyumsuz birkaç lehçe mevcuttur:

• CommonMark (2014, devam eden) — standartlaştırma çalışması. Katı ve öngörülebilir. Çoğu modern ayrıştırıcının uyduğu taban çizgisi.
• GitHub Flavored Markdown (GFM) — CommonMark artı tablolar, üstü çizili metin, görev listeleri, otomatik bağlantılar. Geliştirici belgelerinde fiili standart.
• Pandoc Markdown — akademik ve uzun kitaplar için genişletilmiş: dipnotlar, atıflar, tanım listeleri, LaTeX aracılığıyla matematik.
• Orijinal John Gruber Markdown (2004) — bazı yerlerde yetersiz belgelenmiş. Farklı ayrıştırıcılar köşe durumları farklı işler.

Taşınabilirlik önemliyse CommonMark’a uyun ve lehçeye özgü uzantılardan kaçının.

Markdown içinde HTML

Çoğu Markdown ayrıştırıcısı, Markdown’ın yeterince ifade edemediği durumlarda ham HTML’i satır içine eklemenize izin verir. Bu pratik bir kaçış kapısıdır — belgenizin %95’ini Markdown olarak tutun, colspan gerektiren tablo, video yerleştiren iframe veya form için HTML’e geçin.

Bazı ayrıştırıcılar (örneğin StackOverflow’un) güvenlik için HTML’in büyük bölümünü temizler. Buna güvenmeden önce işleme bağlamını kontrol edin.

Pragmatik kural

• Yazarken: Markdown. Her zaman Markdown ile başlayın.
• Okurken: HTML. Tarayıcı/e-posta, Markdown’ınızın HTML çıktısını işler.
• Köşe durumlar: gerektiğinde satır içi HTML’e geçin.
• E-posta pazarlaması, karmaşık düzenler, üretim web: doğrudan HTML.

Sayısal gerçekler

• Markdown spesifikasyon uzunluğu: CommonMark 0.31 yaklaşık 70 baskı sayfasıdır; WHATWG HTML Yaşayan Standardı >1.400 sayfadır.
• Tuş vuruşu oranı: 6 bağlantı ve 3 başlık içeren tipik bir 500 kelimelik makale için Markdown kaynağı ~620 karakter iken eşdeğer HTML ~1.050 karakterdir — yaklaşık %40 daha az tuş vuruşu.
• Ayrıştırma hızı: markdown-it, 2024 model bir dizüstü bilgisayarda CommonMark’ı ~150 MB/s hızında ayrıştırır; modern HTML ayrıştırıcılar (lxml, html5ever) 200-400 MB/s’dir. Her ikisi de yeterince hızlıdır ve ayrıştırma hiçbir zaman darboğaz olmaz.
• GFM tablo desteği: GitHub Flavored Markdown tabloları 64 sütunla sınırlar; CommonMark spesifikasyonunun yerel tablo sözdizimi yoktur.
• Benimseme sinyali: GitHub’daki README’lerin ~%99’u Markdown’dır (GitHub dosya sayısının 280 milyonu aştığını bildirmektedir).

Yan yana karar matrisi

Tehlikeli noktalar

Belgeleme ardışık düzenleri için Markdown’ı benimseyen ekiplerde üç başarısızlık modu tekrar eder:

• Sabit sarım ve yumuşak sarım paragraflar. CommonMark, paragraf içindeki tek satır sonunu boşluk olarak değerlendirir; GFM aynı kuralı takip eder ancak bazı eski ayrıştırıcılar (eski RedCarpet, eski Pandoc) bunu gerçek <br> olarak işler. Çözüm: satır sonu istemiyor musanız paragraf içinde asla sabit sarım kullanmayın.
• Akıllı tırnak yeniden yazımı. Pandoc, Hugo ve bazı Jekyll eklentileri düz tırnakları sessizce tipografik kıvrık tırnaklara dönüştürür — düz metin için iyidir ancak çitlensiz kod örneği içinde felaket olur. Tırnak işareti içeren her şey için her zaman çitlenmiş kod blokları (üç backtick) kullanın.
• Liste girintileme. CommonMark, iç içe liste öğelerinin üst liste öğesinin işaret uzaklığıyla eşleşecek şekilde 2 veya 4 boşluk girintilenmesini gerektirir. Sekmeler ayrıştırıcılar arasında farklı işlenir; aynı liste içinde sekme ile boşluğu asla karıştırmayın.

Kaynaklar

• CommonMark Spesifikasyonu 0.31.2 — spec.commonmark.org (kanonik Markdown grameri).
• WHATWG HTML Yaşayan Standardı — html.spec.whatwg.org (yetkili HTML referansı).
• GitHub Flavored Markdown Spesifikasyonu — github.github.com/gfm (GitHub’ın kullandığı CommonMark üst kümesi).