Markdown Görüntüleyici

Önizleme ile düzenleyici neden aynı şeyi göstermez

Markdown tek bir dil gibi görünür ama değildir. 2004 teki özgün söz dizimi pek çok şeyi belirsiz bıraktı, CommonMark yıllar sonra kuralları sıkılaştırdı, GitHub ise bunun üzerine kendi eklentilerini koydu. Dolayısıyla iki işleyici aynı anda doğru olup belgeniz hakkında farklı sonuç üretebilir. Düzenleyicide doğru görünen bir dosyanın depo sayfasında bozuk çıkmasının sebebi budur.

Farklar birkaç noktada toplanır: bir listenin üstündeki boş satırla ilişkisi, paragraf içindeki satır sonunun korunup korunmadığı ve ham HTML in başına ne geldiği. Çoğu zaman bunların hiçbiri önemli değildir. Önemli olduğunda ise tam yayımlama anında önem kazanır.

Ham HTML gösterilir, çalıştırılmaz

Markdown standardı ham HTML e izin verir ve GitHub bunun süzülmüş bir alt kümesini işler. Bu görüntüleyici hiçbirini işlemez: kaynağınızdaki HTML etiketleri düz metin olarak görünür.

Bu bir eksiklik değil, bilinçli bir güvenlik sınırıdır. Belge yapıştırmaya davet eden, sonra o belgeyi canlı biçimlendirmeye çeviren bir araç yansıtılmış betik açığıdır; alışılmış çözüm olan süzgeç ise sürekli değişen bir hedefe karşı sonsuza dek bakımı gereken bir izin listesi demektir. Hiçbir şey işlememek, sürekli bakım yükümlülüğü ve başarısızlık senaryosu olmayan tek seçenektir.

1<div align="center">2  <img src="logo.png" width="200">3</div>4 5Yukarıdaki blok burada metin olarak görünür, GitHub ta işlenir.

Pratik sonucu şudur: logosunu div ile ortalayan bir README burada GitHub taki hâlinden farklı görünecektir. Araç HTML tespit ettiğinde bunu açıkça söyler, bir bloğun neden kaybolduğunu size bırakmaz.

Yapı görünümü ve yakalamak için var olduğu kusur

Yapı görünümü her başlığı seviyesi ve kaynak satırıyla listeler, derinliğine göre girintiler. Asıl işi tek bir kusuru görünür kılmaktır: seviye atlaması.

1# Proje başlığı2## Kurulum3#### Gereksinimler     <- H2 den H4 e atlıyor

İşlendiğinde bu gayet düzgün görünür. H4 sadece H3 ten küçüktür ve gözle bir yanlışlık fark edilmez. Ancak yardımcı teknolojiler başlık seviyelerini yapı olarak duyurur; 2 den 4 e atlamak ekran okuyucu kullanan birine bir bölümün eksik olduğunu söyler. Otomatik içindekiler üreten her araç da bundan bozuk bir iç içelik çıkarır.

İstatistikler tam olarak neyi sayar

Kelime sayısı ve okuma süresi, çitli kod bloklarının içeriğini dışarıda bırakır. Kullanışlı bir tahmin ile anlamsız bir tahmin arasındaki fark budur: yarısı kurulum komutlarından oluşan bir README, aksi hâlde kimsenin düz metin gibi okumadığı satırların belirlediği bir okuma süresi bildirirdi.

Çit içinde çit

Bir ayrıştırma ayrıntısı bilinmeye değer, çünkü basit araçları sürekli bozar. Çit üç veya daha fazla ters tırnaktır ve kapatan çit, açan çit kadar uzun olmak zorundadır. Markdown hakkında yazılmış bir belgenin, içinde kod bloğu gösteren bir kod bloğu barındırabilmesini sağlayan kural budur.

1````2```3bu içteki çit bloğu bitirmez4```5````

Karşılaştığı ilk üç ters tırnakta bloğu kapatan bir ayrıştırıcı, dosyanın geri kalanını düz metin sayar; bu da sonraki bütün sayımları kaydırır ve sıradan metni hayalet başlıklara çevirebilir. Bu görüntüleyici hem çit karakterini hem uzunluğunu takip eder.

Hiçbir şey tarayıcınızdan çıkmaz

Belge yerel olarak ayrıştırılır ve işlenir. Hiçbir şey yüklenmez; söz konusu dosya bir iç şartname veya henüz yayımlanmamış bir README olduğunda önemli olan da budur. Sayfa yüklendikten sonra bağlantınızı kesseniz bile araç çalışmaya devam eder.