Dosya Formatları
Markdown Nedir? Sözdizimi, CommonMark ve GFM
Markdown, düz metne birkaç işaretle başlık, liste ve bağlantı eklemenizi sağlayan hafif bir işaretleme dilidir. Tarihçesini, standartlarını ve MD dosyalarını Word ya da PDF'e çevirirken nelerin korunduğunu anlatıyoruz.
Yazar: Hemen Dönüştür Editör EkibiYayınlanma: 6 dk okuma
Bir yazılım projesinin README dosyasını, bir not uygulamasındaki başlıklı listeleri ya da bir sohbet uygulamasında yıldızlarla kalınlaştırdığınız kelimeleri düşünün. Hepsinin arkasında aynı fikir var: Markdown. Markdown, düz metne birkaç basit işaret ekleyerek başlık, liste, bağlantı ve tablo tanımlamanızı sağlayan hafif bir işaretleme dilidir. Dosya her metin düzenleyicide okunabilir kalır, ama istendiğinde temiz bir HTML sayfasına, Word belgesine ya da PDF'e dönüştürülebilir. Bu yazıda Markdown'ın nasıl ortaya çıktığını, temel sözdizimini, CommonMark ile GitHub Flavored Markdown arasındaki farkları ve MD dosyalarını dönüştürürken nelere dikkat etmeniz gerektiğini anlatıyoruz.
Markdown nedir?
Markdown hem bir yazım kuralları bütünü hem de bu kurallarla yazılmış metni HTML'e çeviren araçların ortak adıdır. Dosyalar genellikle .md ya da .markdown uzantısıyla kaydedilir. Markdown'ın yaratıcısı John Gruber'e göre biçimin en temel tasarım hedefi okunabilirliktir: Markdown ile yazılmış bir belge, etiketlerle ya da biçimlendirme komutlarıyla doluymuş gibi görünmeden, olduğu gibi düz metin olarak yayımlanabilmelidir. HTML'de <strong>önemli</strong> yazdığınız yerde Markdown'da **önemli** yazarsınız; ham hali bile okunaklıdır.
Kısa tarihçe
Markdown'ı 2004'te John Gruber oluşturdu; Aaron Swartz bu süreçte fikirlerini sınadığı kişi olarak katkı verdi. Gruber'in sözdizimi, düz metin e-postalarda kullanılan alışkanlıklardan (vurgu için yıldız, liste için tire gibi) ve setext, Textile gibi önceki işaretleme dillerinden beslendi. Gruber'in Daring Fireball sitesinde yayımladığı Perl betiği Markdown.pl'nin 1.0.1 sürümü 17 Aralık 2004 tarihlidir.
Ancak Gruber'in tanımı resmi bir şartname değil, örneklerle anlatılmış bir açıklamaydı. Belirsiz kalan durumlar (iç içe listeler, girintili kod blokları, HTML ile karışık kullanım gibi) her uygulamanın kendi yorumunu yapmasına yol açtı ve aynı metin farklı araçlarda farklı çıktılar üretmeye başladı. Bu dağınıklığa iki önemli yanıt geldi:
- CommonMark (2014): John MacFarlane'in öncülük ettiği, Markdown'ı belirsizlik bırakmayacak şekilde tanımlayan ve yüzlerce örnekle test edilebilir kılan şartname. İlk sürümler 2014 sonbaharında yayımlandı; güncel sürüm 28 Ocak 2024 tarihli 0.31.2'dir. Şartname henüz 1.0 olarak ilan edilmedi.
- GitHub Flavored Markdown (GFM, 2017): GitHub'ın CommonMark üzerine kurduğu resmi şartname. Tablolar, görev listeleri, üstü çizili metin, genişletilmiş otomatik bağlantılar ve güvenlik için bazı ham HTML etiketlerinin engellenmesi gibi uzantılar ekler. Yayımlanan son şartname 6 Nisan 2019 tarihli 0.29-gfm'dir.
Markdown internet altyapısında da tanındı: Mart 2016'da yayımlanan RFC 7763, text/markdown ortam türünü (MIME türü) kaydetti ve hangi Markdown varyantının kastedildiğini belirtmek için isteğe bağlı bir variant parametresi tanımladı.
Başlıca Markdown varyantları
CommonMark ve GFM dışında da yaygın varyantlar vardır. RFC 7763 ile birlikte yayımlanan RFC 7764, bunların bir kısmını kaydetti ve kullanım rehberi sundu:
- Markdown Extra: Dipnotlar, tanım listeleri ve tablolar gibi eklemeler getiren erken bir uzantı.
- MultiMarkdown: Meta veri, kaynakça ve çapraz başvuru gibi akademik yazım ihtiyaçlarına yönelik bir varyant.
- Pandoc Markdown: Pandoc dönüştürücüsünün kullandığı, kitap ve makale yazımı için çok sayıda uzantı içeren varyant.
Pratik kural şudur: Belgeniz yalnızca başlık, liste, bağlantı, kod ve basit tablo içeriyorsa hemen her ortamda aynı görünür. Dipnot, tanım listesi ya da özel blok türleri kullanıyorsanız hedef ortamın varyantını kontrol edin.
Temel sözdizimi
Markdown'ın günlük kullanımda ihtiyaç duyacağınız kısmı birkaç dakikada öğrenilir:
# Birinci düzey başlık
## İkinci düzey başlık
Bu paragrafta **kalın**, *italik* ve `kod` var.
- Madde işaretli liste
- İkinci madde
- Girintili alt madde
1. Numaralı liste
2. İkinci adım
[Bağlantı metni](https://example.com)
> Alıntı bloğu
```
Çok satırlı kod bloğu
```GFM ile gelen tablolar ve görev listeleri ise şöyle yazılır:
| Biçim | Uzantı |
|-------|--------|
| Markdown | .md |
| Düz metin | .txt |
- [x] Taslağı yaz
- [ ] Gözden geçirParagraflar boş satırla ayrılır. Tek bir satır sonu çoğu uygulamada aynı paragrafın devamı sayılır; satırı zorla bölmek için satırı iki boşlukla bitirmeniz gerekir. Markdown içine doğrudan HTML de yazabilirsiniz; CommonMark bunu destekler, ancak GFM gibi bazı ortamlar güvenlik nedeniyle belirli etiketleri engeller.
Nerelerde kullanılır?
- Yazılım geliştirme: README, CHANGELOG ve katkı rehberleri; GitHub, GitLab gibi platformlarda sorun kayıtları ve kod incelemesi yorumları.
- Teknik dokümantasyon: Markdown dosyalarından web sitesi üreten statik site araçları.
- Not alma: Birçok not uygulaması notları Markdown olarak saklar ya da dışa aktarır.
- Sohbet ve topluluk platformları: Reddit ve Discord gibi platformlar Markdown'ın varyantlarını kullanır.
- Yazarlık ve yayıncılık: Pandoc gibi araçlarla tek bir Markdown kaynağından HTML, PDF, DOCX ve EPUB üretmek.
- Yapay zekâ araçları: Sohbet tabanlı yapay zekâ asistanları yanıtlarını çoğu zaman Markdown biçiminde üretir.
Güçlü ve zayıf yönleri
| Güçlü yönler | Zayıf yönler |
|---|---|
| Ham hali bile okunaklı | Varyantlar arasında farklılıklar var |
| Düz metin: küçük, taşınabilir, sürüm kontrolüne uygun | Yazı tipi, renk, sayfa düzeni tanımlanamaz |
| Kolayca HTML, PDF ve Word'e dönüştürülür | Karmaşık tablolar (birleştirilmiş hücreler) desteklenmez |
| Öğrenmesi birkaç dakika | Görseller ayrı dosya olarak durur |
| Belirli bir programa bağımlı değil | Boşluk ve girinti hataları çıktıyı değiştirebilir |
Hangi programlar açar?
Markdown düz metin olduğu için Not Defteri ve TextEdit dahil her metin düzenleyicide açılır. Biçimlendirilmiş önizleme için Visual Studio Code'un yerleşik Markdown önizlemesi, Obsidian ve Typora gibi Markdown düzenleyicileri kullanılabilir. GitHub ve GitLab depolardaki .md dosyalarını otomatik olarak biçimlendirilmiş halde gösterir. Word ise Markdown'ı doğrudan biçimli olarak açmaz; bunun için dosyayı dönüştürmeniz gerekir.
Sık karşılaşılan sorunlar ve çözümleri
Liste ya da başlık oluşmuyor
CommonMark'ta başlık işaretinden sonra bir boşluk gerekir: #Başlık değil ## Başlık. Bir listenin paragraftan sonra doğru oluşması için de çoğu zaman araya boş satır koymak gerekir.
Satırlar birleşiyor
Tek satır sonu paragrafı bölmez. Yeni paragraf için boş satır bırakın, aynı paragraf içinde satır atlamak için satırı iki boşlukla bitirin.
Tablo bir platformda çalışıyor, diğerinde çalışmıyor
Tablolar Gruber'in özgün Markdown'ında ve CommonMark çekirdeğinde yoktur; GFM gibi uzantılarla gelir. Hedef platformun hangi varyantı desteklediğini kontrol edin.
Paragrafın başındaki "1." numaralı listeye dönüşüyor
"2024. yılda" gibi rakam ve noktayla başlayan bir satır liste olarak yorumlanabilir. Noktadan önce ters eğik çizgi koyarak (2024\.) bunu önleyebilirsiniz.
Markdown dönüştürme ipuçları
Dönüştürücümüzde Markdown dosyaları sunucumuza yüklenir ve 30 dakika içinde silinir. Okuma tarafında Markdig kitaplığı CommonMark ve GitHub benzeri uzantılarla (tablolar, görev listeleri, dipnotlar, otomatik bağlantılar) kullanılır.
- Markdown'dan PDF'e ve Markdown'dan Word'e dönüştürmede başlıklar, listeler, kod blokları, alıntılar ve kenarlıklı tablolar korunur. Görev listesi kutucukları Word ve PDF'te de görünsün diye ☑ ve ☐ karakterlerine çevrilir. Metin varsayılan olarak 12 punto serif yazı tipiyle, kod blokları eş aralıklı yazı tipiyle dizilir.
- Markdown'dan HTML'e dönüştürme, bir README dosyasını tek başına açılabilen, karakter kodlaması belirtilmiş bir web sayfasına çevirir.
- Tersine, Word'den Markdown'a, HTML'den Markdown'a ya da PDF'ten Markdown'a dönüştürmede GitHub uyumlu Markdown üretilir: Başlıklar, kalın ve italik metin, listeler, tablolar, bağlantılar, kod blokları ve alıntılar korunur; yazı tipi, renk ve sayfa düzeni atılır. Başlık satırı olmayan tablolarda ilk satır başlık kabul edilir, çünkü GFM tabloları başlık satırı ister. "1. Madde" gibi rakamla başlayan düz paragraflar yanlışlıkla listeye dönüşmesin diye kaçış karakteriyle işaretlenir. Dosya BOM'suz UTF-8 olarak kaydedilir.
Sık Sorulan Sorular
MD dosyası nasıl açılır?
Herhangi bir metin düzenleyiciyle açabilirsiniz. Biçimlendirilmiş halini görmek için Visual Studio Code'un önizlemesini ya da bir Markdown düzenleyicisini kullanın; Word'de okumak istiyorsanız dosyayı DOCX'e dönüştürün.
CommonMark ile GitHub Flavored Markdown arasındaki fark nedir?
CommonMark, Markdown'ın çekirdek sözdizimini kesin kurallarla tanımlar. GFM, CommonMark'ın üzerine tablolar, görev listeleri, üstü çizili metin ve genişletilmiş otomatik bağlantılar gibi uzantılar ekleyen bir üst kümedir.
Markdown'da tablo yapılabilir mi?
Evet, GFM gibi uzantılarla dikey çizgi ve tirelerle basit tablolar yazılabilir. Hücre birleştirme gibi karmaşık yapılar için HTML tablo kullanmak ya da belgeyi Word'de hazırlamak gerekir.
Markdown ile HTML arasındaki fark nedir?
Markdown, HTML'e dönüştürülmek üzere tasarlanmış daha sade bir yazım biçimidir. HTML'in sunduğu her şeyi ifade edemez, ama ham hali çok daha okunaklıdır. Markdown içine gerektiğinde HTML de yazılabilir.
Markdown'ın resmi bir standardı var mı?
Gruber'in özgün tanımı resmi bir şartname değildir. Bugün en yaygın kabul gören kesin tanım CommonMark'tır; text/markdown ortam türü ise Mart 2016'da RFC 7763 ile kaydedilmiştir.
