Markdown Nedir ve .md Dosyası Nasıl Görüntülenir?

Temel söz dizimi ve sık yapılan hatalar

Başlıklar # ile yazılır ve CommonMark'ta # işaretinden sonra boşluk gerekir; #Başlık bir başlık değil sıradan metindir. Kalın ve italik için ** ve * (veya _) kullanılır. Listeler -, * ya da 1. ile başlar. Bağlantı [metin](adres), görsel ise başına ünlem eklenmiş  biçimindedir. Kod blokları üç ters tırnakla açılıp kapanır; açılışa dil adı yazılabilir.

En çok şaşırtan kural satır sonlarıdır. Tek bir satır sonu yeni satır üretmez, iki satır aynı paragrafta birleşir. Yeni paragraf için arada boş satır bırakmak, paragraf içinde satır kırmak için satır sonuna iki boşluk ya da ters eğik çizgi koymak gerekir. Dört boşlukla girintilenmiş satırlar ise kod bloğuna dönüşür; iç içe listeleri girintilerken bu yüzden fazla boşluk sorun çıkarabilir.

GFM tablolarında başlık satırının altında |---|---| biçiminde bir ayırıcı satır zorunludur; bu satır yoksa tablo düz metin olarak kalır. Hücre içinde dikey çizgi kullanmak için \| yazılır. Satır başında 1986. gibi bir yıl yazarsanız metin numaralı listeye dönüşebilir; noktadan önce ters eğik çizgi koymak bunu önler.

Bağlantı adreslerindeki boşluklar da sorun çıkarır. [rapor](belgeler/yıllık rapor.pdf) biçimindeki bir bağlantı bağlantı olarak tanınmaz; boşluk yerine %20 yazmak ya da adresi köşeli ayraç içine almak (<belgeler/yıllık rapor.pdf>) gerekir. Başlıkların hemen öncesinde ve sonrasında boş satır bırakmak, farklı işleyicilerde aynı sonucu almanın en kolay yoludur.

Markdown görüntüleyici ne gösterir, ne göstermez?

Görüntüleyici, marked kütüphanesini GFM modu açık olarak kullanır. Tablolar, görev listeleri (işaretlenemeyen onay kutularıyla), üstü çizili metin ve www ile başlayan otomatik bağlantılar işlenir. Önizleme ve Kaynak sekmeleri arasında geçiş yapılır; kaynak görünümü satır numaralıdır. Düzenle ile metni değiştirip .md olarak indirebilirsiniz. .md, .markdown ve .mdx uzantıları kabul edilir, ancak MDX içindeki bileşenler çalıştırılmaz.

marked'ın belgeleri kütüphanenin çıktıyı temizlemediğini ve DOMPurify gibi bir temizleyici önerdiğini açıkça yazar. Sitede üretilen HTML DOMPurify'dan geçirilir: script ve style blokları, formlar ve gömülü çerçeveler atılır, bağlantılar yeni sekmede açılır. Bu sayede bilinmeyen bir kaynaktan gelen README'yi önizlemek, içindeki ham HTML'in sayfada kod çalıştırmasına yol açmaz.

Desteklenmeyenleri bilmek, gördüğünüz farkı yorumlamayı kolaylaştırır. Dipnotlar ve $x^2$ biçimindeki matematik ifadeleri düz metin kalır, Mermaid blokları kod bloğu olarak görünür. Dosyanın başındaki --- ile çevrili YAML ön bilgisi yatay çizgi ve büyük bir başlık gibi görünür, çünkü bu blok Markdown'ın değil ön bilgi kullanan araçların özelliğidir. docs/logo.png gibi göreli yollu görseller yalnızca .md dosyası yüklendiği için bulunamaz. https ile başlayan uzak görsellerse tarayıcınız tarafından ilgili sunucudan istenir.

Kod bloklarında dil adı (örneğin ```python) HTML'e bir sınıf olarak eklenir, ama bu görüntüleyici sözdizimi renklendirmesi yapmaz; kod tek renkli, eşit aralıklı yazıyla görünür. README'lerde sık kullanılan sürüm ve derleme rozetleri de uzak görsellerdir. Bu rozetleri içeren bir dosyayı önizlediğinizde tarayıcı rozet servislerine istek gönderir; çevrimdışıyken ya da servis erişilemezken yerlerinde yalnızca açıklama metni kalır.

Pratik kullanım senaryoları

En yaygın kullanım, bir depoya göndermeden önce README'nin nasıl görüneceğini kontrol etmektir: başlık hiyerarşisi, tablo sütunları ve kod bloklarının kapanıp kapanmadığı bir bakışta anlaşılır. Sonuç GitHub'daki görünüme yakın olur, ama GitHub'a özgü uyarı kutuları gibi eklentiler burada düz alıntı olarak kalabilir.

Teknik yazı ekipleri Markdown'ı bir sürüm kontrol sisteminde tuttukları dokümantasyon için de kullanır. Bir değişiklik isteğinde gelen .md dosyasını indirip önizlemek, ham farklara bakarken gözden kaçan bozuk tabloları, kapanmamış kod bloklarını ve yanlış seviyedeki başlıkları yakalamayı kolaylaştırır. Kapanmamış bir kod bloğu, dosyanın geri kalanının tamamını kod gibi gösterdiği için önizlemede hemen fark edilir

İndirdiğiniz bir yazılım paketinin dokümantasyonunu okumak için ZIP'i çıkarmanız gerekmez: ZIP görüntüleyicide .md dosyasının yanındaki Önizle düğmesi dosyayı doğrudan Markdown görüntüleyicide açar. Jupyter not defterlerindeki Markdown hücreleri de sitedeki notebook görüntüleyicide aynı kütüphaneyle işlenir.

Obsidian gibi not uygulamalarından dışa aktarılan dosyalarda [[Başka not]] biçimindeki iç bağlantılar Markdown standardının parçası olmadığı için köşeli ayraçlarıyla düz metin olarak kalır. Notlar arası bağlantıları korumak istiyorsanız dışa aktarırken standart Markdown bağlantılarına dönüştürme seçeneğini arayın. Aynı şekilde not uygulamalarının etiket ve geri bağlantı özellikleri de yalnızca o uygulamanın içinde anlam taşır; dosyayı dışarıda açtığınızda bunlar sıradan metin olarak görünür.

Düzenle ile yaptığınız değişiklikler yalnızca tarayıcıdaki kopyada kalır ve İndir ile UTF-8 kodlu yeni bir .md dosyası olarak alınır; özgün dosyanın üzerine yazılmaz. Görüntüleyici Markdown'ı PDF veya Word'e dönüştürmez. Biçimli bir çıktıya ihtiyacınız varsa Pandoc gibi bir dönüştürücü kullanmak daha uygundur. Dosya tarayıcınızda işlenir ve sunucuya yüklenmez.