Markdown Kullanım Kılavuzu: Belge Oluşturma ve Biçimlendirme Rehberi

Markdown Nedir ve Neden Kullanmalısınız?

Markdown, basit ve okunabilir metin tabanlı bir biçimlendirme dilidir. HTML'e göre çok daha kolay öğrenilir ve kullanılır. Özellikle geliştiriciler, teknik yazarlar ve içerik üreticileri tarafından tercih edilir. Markdown kullanmanın en büyük avantajı, farklı platformlarda (GitHub, GitLab, VS Code, Notion vb.) tutarlı bir şekilde görüntülenmesidir.

Belge Yapısı Oluşturma

Markdown belgeleri oluştururken başlıklar ve bölümler oluşturmak temel gereksinimdir. Aşağıdaki yöntemlerle belge yapısını düzenleyebilirsiniz:

# Başlık 1 (En üst düzey başlık)
## Başlık 2 (İkinci düzey başlık)
### Başlık 3 (Üçüncü düzey başlık)
#### Başlık 4 (Dördüncü düzey başlık)
##### Başlık 5 (Beşinci düzey başlık)
###### Başlık 6 (Altıncı düzey başlık)

Örnek:

# Proje Dokümantasyonu
## Giriş
### Kurulum
#### Gereksinimler
##### Sürüm Kontrolü

Belge bölümlerini ayırmak için yatay çizgiler kullanabilirsiniz:

---

Paragrafları ayırmak için boş satır bırakın:

Bu ilk paragraf.

Bu ikinci paragraftır.

HTML Yorumları

Markdown belgelerine HTML yorumları ekleyebilirsiniz. Bu, belgeyi işlerken kullanışlı olabilir:

<!-- Bu bir HTML yorumudur -->

İpucu: HTML yorumları, belgeyi işlerken kullanışlıdır ancak çıktıda görünmezler. Gizli notlar eklemek için idealdirler.

Metin Biçimlendirme

Metinleri farklı stillerde biçimlendirmek için aşağıdaki yöntemleri kullanın:

Biçimlendirme	Markdown Söz Dizimi	Örnek Çıktı
Kalın (Bold)	**kalın metin** veya __kalın metin__	kalın metin
İtalik	*italik metin* veya _italik metin_	italik metin
Kalın ve İtalik	***kalın ve italik*** veya ___kalın ve italik___	kalın ve italik
Üstü Çizili	~~üstü çizili~~	üstü çizili
Inline Kod	`kod bloğu`	kod bloğu
Alt Simge	<sub>alt simge</sub>	H2O
Üst Simge	<sup>üst simge</sup>	X<sup>2</sup>

Bağlantılar ve Resimler

Markdown ile hem metinlere hem de resimlere bağlantılar ekleyebilirsiniz. Bu özellik, belgeye dinamiklik kazandırır.

Metin Bağlantıları

Standart bağlantı oluşturma:

[Linuxize Web Sitesi](https://linuxize.com)

Belge içi bağlantı (anchor):

[Bağlantı Metni](#belge-içi-bağlantı)

Referans bağlantıları (daha okunabilir ve yönetilebilir):

[Bağlantı Metni][id]

[id]: https://linuxize.com

Resim Ekleme

Resim eklemek için:

![Alternatif Metin](resim-dosyası.jpg)

Resme bağlantı eklemek:

[![Alternatif Metin](resim-dosyası.jpg)](https://ornek.com)

Uyarı: Resim yollarını belirtirken göreceli yollar kullanın (örn: ./images/logo.png) ve dosyaları proje dizininde organize edin.

Listeler Oluşturma

Markdown, sıralı (ordered) ve sırasız (unordered) listeler oluşturmanıza olanak tanır. Ayrıca görev listeleri de oluşturabilirsiniz.

Sırasız Listeler

- Madde 1
- Madde 2
* Madde 3
* Madde 4

Sıralı Listeler

1. İlk madde
2. İkinci madde
3. Üçüncü madde

Görev Listeleri

Tamamlanabilir görevler oluşturun:

- [x] Tamamlanmış görev
- [ ] Tamamlanmamış görev

İç İçe Listeler

- Ana madde
  - Alt madde 1
  - Alt madde 2
    - Alt-alt madde

Kod Blokları ve Komutlar

Markdown, kod blokları oluşturmak için özel bir sözdizimine sahiptir. Bu, özellikle geliştiriciler için faydalıdır.

Inline Kod

Metin içinde kısa kod parçacıkları için:

Bu bir `inline` kod örneğidir.

Çok Satırlı Kod Blokları

Belirli bir programlama diline ait kod blokları oluşturun:

python
print("Merhaba Dünya")
def topla(a, b):
    return a + b

Dil belirtmeden genel kod bloğu:

Bu bir genel kod bloğudur
Çok satırlı metin

Girintili Kod Blokları

Dört boşluk girintileme kullanarak kod blokları oluşturun (eski yöntem):

    def fonksiyon():
        print("Merhaba")
        return 0

İpucu: Fenced code block () yöntemi, girintili bloklara göre daha okunabilir ve modern bir yaklaşımdır. Öncelikle bu yöntemi tercih edin.

Tablolar Oluşturma

Markdown, basit tablolar oluşturmanıza olanak tanır. Tabloları dikey çizgiler (|) ve tireler (-) kullanarak oluşturun.

| Başlık 1 | Başlık 2 | Başlık 3 |
|-----------|-----------|-----------|
| Hücre 1  | Hücre 2  | Hücre 3  |
| Hücre 4  | Hücre 5  | Hücre 6  |

Sütun hizalaması:

| Sol Hizalama | Ortalama | Sağ Hizalama |
|:-------------|:---------:|-------------:|
| Sol          | Ortalama | Sağ          |
| Veri         | Veri     | Veri         |

Alıntılar (Blockquotes)

Metinleri alıntılamak ve çok satırlı alıntılar oluşturmak için kullanılır.

> Bu bir tek satırlık alıntıdır

> Bu bir
> çok satırlı
> alıntıdır

İç içe alıntılar:

>> Bu bir dış alıntıdır
>>>> Bu bir iç alıntıdır

Listeler içeren alıntılar:

> - Liste maddesi 1
> - Liste maddesi 2
>   - Alt madde

Özel Karakterlerden Kaçınma (Escaping)

Markdown özel karakterleri (*, #, [, ], vb.) biçimlendirme amacıyla kullanır. Bu karakterleri normal metin olarak görüntülemek için kaçış karakteri (backslash \ ) kullanın.

\* Bu bir yıldız işaretidir \*
\# Bu bir hash işaretidir
\[Bu köşeli parantezlerdir\]
\<bu açısal parantezlerdir>
\& Bu bir ampersand işaretidir

Yaygın Markdown Uzantıları

Birçok Markdown render'ında desteklenen yaygın uzantılar:

Uzantı	Açıklama
Görev Listeleri	- [x] Tamamlanan görev
Üstü Çizili	~~üstü çizili metin~~
Emoji Kısayolları	:smile: :rocket: :tada:
Dipnotlar	[^1] ve [^1]: Dipnot içeriği
Tanımlama Listeleri	Terim : Tanım

Not: Tüm Markdown render'ları bu uzantıları desteklemeyebilir. Destek durumu için kullanacağınız platformun belgelerini kontrol edin.

Markdown Dosyalarını Yönetme İpuçları

1. Dosya Uzantıları: Markdown dosyaları genellikle .md veya .markdown uzantısına sahiptir.
2. Versiyon Kontrolü: Git ile birlikte kullanıldığında, değişiklikleri takip etmek kolaydır. git add, git commit ve git push komutlarını kullanın.
3. Düzenleyiciler: VS Code, Typora, Obsidian ve Notion gibi araçlar Markdown düzenlemeyi kolaylaştırır.
4. Önizleme: Düzenlediğiniz Markdown dosyasının nasıl görüneceğini görmek için preview özelliğini kullanın.
5. Standartlar: Ekip içinde çalışırken, Markdown standartlarını belirleyin (örn: başlık seviyeleri, liste stilleri).

Sık Karşılaşılan Sorunlar ve Çözümleri

Sorun: Tablolar düzgün görünmüyor

Çözüm:

1. Tüm satırlarda aynı sayıda sütun olduğundan emin olun.
2. Ayırıcı satırdaki tire (-) sayısının yeterli olduğundan emin olun.
3. Sütun hizalaması için doğru sayıda kolon kullanın.

Sorun: Kod blokları düzgün render edilmiyor

Çözüm:

1. Kod bloklarını oluştururken dil belirtin (örn: python).
2. Üç adet backtick kullanın ve dil adını belirtin.
3. Eğer kod bloğu içinde üç adet backtick varsa, dışarıyı dört adet backtick ile çevreleyin.

Sorun: Resimler görüntülenmiyor

Çözüm:

1. Resim dosyalarının doğru yolda olduğundan emin olun.
2. Dosya adlarında boşluk veya özel karakter olmadığından emin olun.
3. Resim yolunu göreceli olarak belirtin (örn: ./images/logo.png).

Markdown'ı Öğrenmek İçin Kaynaklar

• Markdown Guide - Kapsamlı Markdown rehberi
• Daring Fireball - Markdown'ın yaratıcısından resmi dokümantasyon
• Markdown Cheatsheet (GitHub) - Hızlı referans
• CommonMark - Standart Markdown spesifikasyonu