Markdown Nedir? Sıfırdan Pratiğe Eksiksiz Söz Dizimi Rehberi

Bir README dosyası açtığınızda, bir GitHub issue'su yazdığınızda ya da not uygulamanızda metni kalınlaştırdığınızda büyük ihtimalle Markdown kullanıyorsunuzdur. Markdown, düz metni okunabilir tutarken birkaç basit işaretle biçimlendirmenizi sağlayan hafif bir işaretleme dilidir. 2004'te John Gruber tarafından tasarlanan amacı netti: insanlar kaynak metni de bir sayfa kadar rahat okuyabilsin. Bu yazıda Markdown'ı sıfırdan, ezberlemeden öğrenmenizi sağlayacak her şeyi pratik örneklerle topladık.

Markdown Nerede Kullanılır?

Markdown bugün yazılım ve içerik dünyasının ortak dilidir. En sık karşılaştığınız yerler:

• GitHub / GitLab: README, issue, pull request açıklamaları ve wiki sayfaları.
• Dokümantasyon: Docusaurus, MkDocs, GitBook gibi araçlar Markdown'dan site üretir.
• Statik site üreticileri: Next.js, Hugo, Jekyll, Astro blog yazılarını Markdown olarak tutar.
• Not uygulamaları: Obsidian, Notion, Bear, Joplin Markdown tabanlıdır.
• Sohbet ve forumlar: Slack, Discord, Reddit ve Stack Overflow Markdown'ın bir alt kümesini destekler.

Tek bir söz dizimini öğrenip onlarca platformda kullanabilmeniz, Markdown'ı bu kadar değerli kılan asıl şeydir.

Temel Söz Dizimi

Aşağıda en sık kullanılan öğeleri, hem kaynak metni hem de ekranda nasıl göründüğünü açıklayarak veriyoruz.

Başlıklar

Satır başına # koyarsınız; sayı arttıkça başlık küçülür (# en büyük, ###### en küçük).

# Birinci Seviye Başlık
## İkinci Seviye Başlık
### Üçüncü Seviye Başlık

Sonuç: tıpkı bu yazıdaki gibi büyükten küçüğe doğru kademeli başlıklar elde edersiniz. # ile metin arasına mutlaka bir boşluk koyun.

Kalın, İtalik ve Üstü Çizili

**kalın metin**
*italik metin*
***kalın ve italik***
~~üstü çizili~~

Sonuç: kalın metin, italik metin, ikisi birden ve üstü çizili olarak görünür. İtalik için _alt çizgi_ da kullanılabilir.

Listeler

Sırasız liste için -, * veya +; sıralı liste için 1. kullanın. İç içe liste için iki ya da dört boşluk girinti verin.

- Elma
- Armut
  - Yeşil armut
  - Kırmızı armut
- Kiraz

1. Suyu kaynat
2. Çayı demle
3. Servis et

Sonuç: madde imli ve numaralı listeler oluşur; girintili maddeler bir alt seviye olarak iç içe görünür. Sıralı listede numaraları hep 1. yazsanız bile tarayıcı otomatik sayar.

Bağlantılar ve Görseller

[MagmaNex Araçları](https://magmanex.com/tr/tools/)
![Logo açıklaması](https://magmanex.com/logo.png)

Sonuç: ilki tıklanabilir bir bağlantı, ikincisi ise (başında ! olduğu için) sayfaya gömülmüş bir görseldir. Köşeli parantez içindeki metin, görsellerde alt metni olarak da çalışır.

Alıntılar, Satır İçi Kod ve Yatay Çizgi

> Bu bir alıntıdır.
> Birden fazla satır olabilir.

Komutu `npm install` ile çalıştırın.

---

Sonuç: > ile başlayan satırlar girintili bir alıntı bloğu; ters tırnak içindeki metin tek satırlık kod olarak; --- ise sayfayı bölen yatay bir çizgi olarak görünür.

Kod Blokları

Birden çok satır kod için üç ters tırnak (fenced code block) kullanın ve dil adını yazarak sözdizimi renklendirmesi alın.

```python
def selam(isim):
    return f"Merhaba {isim}"
```

Sonuç: tek tip yazı tipiyle, satır boşlukları korunarak ve diline göre renklendirilmiş bir kod kutusu elde edersiniz.

Hızlı Başvuru Tablosu

Markdown'da Tablolar

Tablolar dik çizgi (|) ile sütunları, ikinci satırdaki kısa çizgilerle de başlığı ayırır. İki nokta üst üste ile hizalama belirleyebilirsiniz.

| Ürün     | Fiyat | Stok |
| :------- | ----: | :--: |
| Klavye   |   450 |  Var |
| Mouse    |   200 | Yok  |

Sonuç: başlık satırı kalın, :--- sola, ---: sağa, :---: ortaya hizalı sütunlar oluşur. Hücrelerin tam hizalı olması zorunlu değildir; tek | yeterlidir.

Görev Listeleri ve GFM

GitHub-Flavored Markdown (GFM), standart Markdown'a pratik eklentiler katar. En sevileni görev listeleridir:

- [x] Tasarımı tamamla
- [ ] Testleri yaz
- [ ] Yayına al

Sonuç: işaretlenebilir kutucuklar görünür; [x] dolu, [ ] boş gelir. GFM ayrıca tabloları, üstü çizili metni, otomatik bağlantı algılamayı ve ```diff gibi sözdizimi vurgularını destekler. Slack veya Discord gibi platformların bazı öğeleri (örneğin görselleri) desteklemediğini unutmayın; hedef platformun lehçesini bilmek önemlidir.

Sık Yapılan Hatalar ve İpuçları

• Boş satır bırakın: Bir başlık, liste veya kod bloğunun öncesinde/sonrasında boş satır olmazsa çoğu işleyici onu doğru yorumlamaz. En sık görülen hata budur.
• Özel karakterleri kaçırın: *, _, #, ` gibi karakterleri düz metin olarak göstermek için önlerine ters eğik çizgi koyun: \*yıldız\* ekranda *yıldız* olarak çıkar.
• Zorunlu satır sonu: Markdown tek Enter'ı yeni paragraf saymaz. Aynı paragrafta alt satıra geçmek için satır sonuna iki boşluk koyun ya da boş satır bırakarak yeni paragraf açın.
• Liste girintisi tutarlı olsun: İç içe listelerde boşluk sayısını karıştırmak (3 boşluk gibi) beklenmedik sonuçlar verir; 2 veya 4 boşlukta sabit kalın.
• Tabloda dik çizgiyi kaçırın: Hücre içinde gerçek bir | göstermek isterseniz \| yazın.

Nasıl Önizler ve Dönüştürürsünüz?

Markdown yazarken sonucu anında görmek işi kolaylaştırır. Yazıp canlı önizleme almak için Markdown editörümüzü kullanabilirsiniz. Yazınızı bir web sayfasına gömmek üzere Markdown'dan HTML'e dönüştürücü ile temiz HTML çıktısı alabilir, tablo yazmaktan yorulduysanız Markdown tablo oluşturucu ile birkaç tıkla düzgün tablolar üretebilirsiniz. Tersine, elinizdeki HTML'i Markdown'a çevirmek için HTML'den Markdown'a dönüştürücüyü deneyin.

Markdown'ın güzelliği, öğrenmesi yarım saat sürerken kazandırdığı verimliliğin yıllarca sürmesidir. Birkaç örnek yazdıktan sonra söz dizimi parmaklarınıza yerleşecek ve bir daha biçimlendirme menülerine ihtiyaç duymayacaksınız.