Açık konuşayım: 20 küsur yıllık BT kariyerimde, geliştiricilerin “ben kod yazarım, dökümantasyon başkasının işi” dediğini sayamayacağım kadar çok duydum. Sonra ne oluyor? Açıyorsun GitHub repo’şunu, README boş kalmış ya da dümdüz metin olarak duruyor, kimse projeye iki saniyeden fazla bakmıyor — valla güzel iş çıkarmışlar —. Hâlbuki Markdown öğrenmek… 1 saatlik iş. Belki 2.
Geçen ay bir bankacılık müşterimde tam da bu yüzden ufak bir iç eğitim verdim. DevOps ekibinin yarısı Azure DevOps wiki’lerine düz metin basıyordu, üstüne bir de “neden kimse bu dokümanları okumuyor” diye soruyorlardı. Cevap aslında basit: Göze hitap etmiyor. İşin aslı bu kadar; biraz düzen, biraz başlık, biraz nefes alanı koyunca tablo değişiyor.
Durun, bir saniye.
Bu yazıda Markdown’ın temellerini, GitHub’a özgü küçük numaraları. — daha da önemlisi — kurumsal ortamlarda nereye nasıl uygulandığını anlatacağım. Hem yeni başlayan biri için iş görür, hem de “ben zaten biliyorum” diyenlerin bile atlayıp geçmemesi gereken birkaç nokta var. İşte, peki neden? Çünkü iyi yazılmış bir README bazen koddan önce konuşuyor.
Markdown Tam Olarak Nedir?
Bi saniye — Lafı dolandırmadan söyleyeyim: Markdown, düz metni biçimlendirmek için kullanılan hafif bir işaretleme dili (şaşırtıcı ama gerçek). HTML’in karmaşıklığı yok, Word’ün de o ağır havası yok; yıldız, tire, kare parantez gıbı birkaç karakterle başlık, liste, link, kalın yazı yapıyorsun. Kısa iş. Ama işin aslı şu: bu sadelik yüzünden insan bir süre sonra “ben bunu niye daha önce kullanmadım ki” diye düşünüyor.
Bunu biraz açayım.
2004’te John Gruber tarafından ortaya çıkarıldı. Bugün GitHub, GitLab, Bitbucket, Notion, Obsidian, Discord, Reddit… aklınıza gelen çoğu teknik platformda karşınıza çıkıyor. Bir kere öğrendin mi, sonra sağda solda sürekli işine yarıyor. Evet. Hatta bazen fark etmeden kullanıyorsun bile.
GitHub’ın kendi GitHub Flavored Markdown (GFM) diye bir sürümü var. Standart Markdown’a görev listeleri, tablolar, otomatik link tanıma ve emoji desteği gıbı şeyler ekliyor; ilk bakışta küçük detay gıbı duruyor ama bir dokümanda düzen kurarken baya iş görüyor. Çoğu zaman aslında GFM yazıyoruz, sadece adını koymuyoruz.
Nerede Karşımıza Çıkıyor?
Doğrusu, En bariz yer README dosyaları. Ama iş orada bitmiyor, hiç bitmiyor aslında; issue açarken, pull request açıklaması yazarken, discussion’larda, wiki’lerde, hatta yorumlarda bile Markdown çıkıyor karşınıza. Kısacası her köşede var.
Bir de son dönemde iyice yayılan agent instruction files işi var — mesela Copilot için .github/copilot-instructions.md dosyası. Yapay zekâ ajanlarına talimat verirken bile Markdown yazıyoruz artık, garip ama öyle. Siz ne dersiniz? Bu arada bu konuya Microsoft Agent Framework’te Chat History: Nerede yazımda biraz dokunmuştum, isterseniz oraya da bir bakın.
Hızlı Bir Test Ortamı Kurmak
Garip gelecek ama, Bir şeyi gerçekten öğrenmek istiyorsanız deneyin. Lafı gevelemeden şöyle yapın: GitHub’da kendi repo’nuza gidin (yoksa açın, cidden 30 saniye sürer), sonra Add file → Create new file deyin. Dosya adını deneme.md verin; .md uzantısı şart, önü atlamayın. İçine iki satır bir şeyler yazın, ardından sağ üstteki Preview sekmesine basın.
Commit etmeye gerek yok. Sayfayı kapatın gitsin, iş bitti; bu sadece deneme amaçlı bir şey zaten. Evet.
Temel Söz Dizimi: En Çok Kullanacaklarınız
Başlıklar
Diyez (#) koyuyorsunuz, iş bitiyor. Kaç tane diyez varsa başlık da ona göre küçülüyor; basit gıbı duruyor ama ilk bakışta insanın kafası azıcık karışabiliyor (evet, doğru duydunuz)
# En büyük başlık (H1)
## Alt başlık (H2)
### Daha alt (H3)
#### Ve devam ediyor (H4)Tuhaf ama, Pratikte ben şunu öneriyorum: README içinde bir tane H1 kullanın, önü da proje adı için ayırın. Geri kalan yapıyı H2 ve H3 ile kurun; hem okunması kolay oluyor hem de SEO tarafında fena olmayan bir düzen çıkıyor — evet, GitHub README’leri Google’da görünebiliyor, o yüzden bu detay boş değil.
Kalın, İtalik, Üstü Çizili
Bu bölüm çok temel, tamam. Ama durun bir saniye, küçük bir kıvrım var:
**kalın**→ kalın*italik*veya_italik_→ italik***ikisi birden***→ ikisi birden~~üstü çizili~~→üstü çizili
Açık konuşayım, Tuzak şu: Bazı Markdown işleyicileri tek alt çizgiyi italik saymıyor, yıldız bekliyor; bazısı da tam tersine takılıyor. Yanı hangı platformda yazıyorsanız ona göre tutarlı gidin, yoksa ufak bir biçim farkı yüzünden gereksiz uğraşırsınız. Ben kendi tarafta yıldızla devam ediyorum, kafa rahat ediyor.
Listeler — Sıralı ve Sırasız
- Birinci madde
- İkinci madde
— İç içe madde (2 boşluk girinti)
— Bir tane daha
1. Sıralı liste
2. İkinci
3. Üçüncüİtiraf edeyim, Söylemeden geçmeyeyim: Sıralı listede numaraları yanlış yazsanız bile Markdown çoğu zaman toparlıyor. Mesela 1, 1, 1 yazdığınızda çıktı tarafında yine 1, 2, 3 görüyorsunuz; hani biraz tembellik ödüllendiriliyor gıbı ama iş görüyor açıkçası.
Görev Listeleri (GFM özel)
- [x] Tamamlanmış görev
- [ ] Bekleyen görev
- [ ] Bir tane dahaBunu özellikle issue’larda çok kullanıyoruz. Kurumsal projelerde sprint task’larını issue altına böyle yazınca takıp işi baya rahatlıyor; GitHub da bunları PR Dashboard’da progress gıbı gösteriyor, yanı ekip ne durumda hemen anlıyor. Bu arada Yeni GitHub PR Dashboard: Artık Varsayılan Geliyor yazımda yeni dashboard’un detaylarına girmiştim, bakarsanız fena olmaz.
Linkler, Resimler ve Kod Blokları
Link Yazmanın 3 Farklı Yolu
Çoğu kişi ilk yöntemi biliyor. Diğer ikisi işe biraz gözden kaçıyor (şaşırtıcı ama gerçek)
[Inline link](https://example.com)
[Referans linki][1]
[1]: https://example.com
<https://example.com> (otomatik link)Referans stilini ne zaman kullanırım? Uzun bir dokümanda aynı linki 5-6 kere kullanacaksam, en alta bir kez tanımlarım, sonra her yerde [1] ile çağırırım (şaşırtıcı ama gerçek). İşin aslı, bakım tarafı baya rahatlıyor; link değişirse tek yerden düzeltirsiniz, gerisi de peşinden gelir. Ben uzun teknik dokümanlarda genelde böyle gidiyorum. Bu konuyla ilgili Azure Cosmos DB Conf 2026: Notlarım, İzlenimlerim ve yazımıza da göz atmanızı tavsiye ederim.
Resimler
Burada kritik bir nokta var: alt metni boş bırakmayın. Erişilebilirlik için bu iş gerçekten önemli. Ekran okuyucu kullanan biri, sizin diyagramı ya da görseli başka türlü anlayamaz; tek kapı çoğu zaman bu oluyor. Ben ekiplerde bunu defalarca söyledim, yine de  diye geçiştiren çıkıyor. Maalesef.
Kod Blokları
Kendi deneyimimden konuşuyorum, İki tür var: satır içi ve blok. Kısacası bu kadar.
Satır içi: `npm install` gibi.
Blok için üç ters tırnak:
```javascript
const x = 5;
console.log(x);
```Ne yalan söyleyeyim, Dil belirtmenin faydası syntax highlighting tarafında çıkıyor. javascript, python, bash, yaml, csharp, powershell… liste uzuyor da uzuyor, yanı destek baya geniş. Ben Azure CLI komutlarında neredeyse her zaman bash ya da powershell yazıyorum. Kopyala-yapıştır sonrası sürpriz azalıyor, komutlar da daha okunur kalıyor (yanlış duymadınız). Hani küçük detay gıbı duruyor ama fark ediyor.
Küçük bir uyarı: README’nize uzun YAML veya JSON bloğu yapıştırırken iki kere düşünün. Eğer 50 satırı geçiyorsa, ayrı bir dosyaya taşıyıp linkleyin. Mobilde okumak zorlaşıyor, parmakla kaydırırken insanın gözü yoruluyor; ayrıca düz metin içinde kaybolan hata ayıklama detayları da cabası.
Tablolar — Hayatımı Kurtaran Şey
Markdown’da en çok sevdiğim numara bu, açık konuşayım. Karşılaştırma yaparken de iş görüyor, parametre listesi verirken de, fiyatları yan yana dizerken de… yanı nereye baksanız bir yere oturuyor. Bir de ilk bakışta basit duruyor ama işin içine girince baya fark ettiriyor. Cosmos DB Maliyet Optimizasyonu: AI Yüklerinde 7 Taktik yazımızda bu konuya da değinmiştik.
| Özellik | Free Plan | Pro Plan |
|---------|-----------|----------|
| Repo | Sınırsız | Sınırsız |
| Actions dakikası | 2.000 | 3.000 |
| Copilot | Yok | Var |Çıktısı şöyle oluyor:
| Özellik | Free Plan | Pro Plan |
|---|---|---|
| Repo | Sınırsız | Sınırsız |
| Actions dakikası | 2.000 | 3.000 |
| Copilot | Yok | Var |
İki nokta üst üste ile hizalama da yapabiliyorsunuz: :--- sola, :---: ortaya, ---: sağa. Bir bakıma, hani küçük detay gıbı duruyor ama tabloyu okurken gözün rahat ediyor. Peki neden? Çünkü bazen tek satırlık bir ayar, bütün görünümü toparlıyor; garip ama gerçek. Bu konuyla ilgili Copilot Cloud Agent %20 Daha Hızlı: Custom Image Etkisi yazımıza da göz atmanızı tavsiye ederim.
Türkiye’deki Şirketler İçin Pratik Notlar
Şimdi işin Türkiye tarafına gelelim. Logosoft’ta danışmanlık verdiğim şirketlerin çoğunda aynı dert çıkıyor: dokümantasyon kültürü baya zayıf. “Kod kendi kendini anlatır” diyorlar, güzel laftır aslında,. 6 ay sonra projeye yeni biri girince o cümlenin pek de öyle durmadığı hemen ortaya çıkıyor.
Şimdi gelelim işin can alıcı noktasına.
Vallahi, Geçen yıl bir e-ticaret şirketinde mikro servis mimarisine geçiş yaptık. Her servis için tek tıp bir README şablonu hazırladık — Markdown ile, evet. İçine de birkaç şey koyduk; çünkü boş bırakınca kimse dönüp bakmıyor, ama düzgün yazınca ekip rahat ediyor: (inanın bana)
- Servis amacı (2-3 cümle, net olsun)
- Teknoloji yığını (tablo hâlinde)
- Local’de çalıştırma adımları (kopyala-yapıştır komutlar)
- Environment değişkenleri (tablo)
- API endpoint listesi (kısa açıklamayla)
- Sahibi/iletişim (kim sorumlu, kime sorulacak)
3 ay sonra ekipten biri mesaj attı: “Aşkın bey, yeni gelen junior’lar artık ilk gün servisi kendi başlarına ayağa kaldırıyor.” Bak şimdi, işte olay bu. İyi yazılmış bir README bazen bütün onboarding yükünü hafifletiyor; para harcamıyorsun, ekstra araç kurmuyorsun, sadece servis başına 30 dakika ayırıyorsun ve sonuç şaşırtıcı derecede iş görüyor.
Kısacası, garip gelecek ama, Tam da öyle.
Enterprise vs Startup: Farklı Yaklaşımlar
İlginç olan şu ki, Küçük bir startup’ta çalışıyorsanız, açık konuşayım, işi fazla büyütmeyin. Bir README, bir CONTRIBUTING.md, belki bir CHANGELOG.md çoğu zaman yeterli oluyor; üstüne 15 farklı doküman çıkarıp kimsenin açmayacağı bir wiki kurmanın pek anlamı kalmıyor.
Şunu fark ettim: Ama 200 kişilik bir geliştirme ekibiniz varsa tablo değişiyor. Orada standart şablonlar, ADR (Architecture Decision Records) dosyaları ve runbook’lar devreye giriyor (özellikle operasyon tarafı sıkıntılıysa daha da çok), hatta ben bir bankada gördüğüm en düzenli ekipte PR template’lerinin bile Markdown checklist’iyle açıldığını hatırlıyorum — “Test yazıldı mı?”, “Security review yapıldı mı?” diye soruyorlar. Kısa soru şu: Sizde bunlar var mı?
Açıkçası, Evet. Bu konuyla ilgili .NET 10’da API Versioning ve OpenAPI: Pratik Entegrasyon yazımıza da göz atmanızı tavsiye ederim.
Sık Yapılan 3 Hata
Yıllar içinde en çok karşıma çıkan şeyler bunlar öldü. Kulağa basit geliyor,. Iş pratikte biraz dağılıyor; özellikle de acele ederken insanın gözüne küçük detaylar görünmüyor, sonra bir bakıyorsunuz çıktı bambaşka yere gitmiş (bizzat test ettim)
1. Boşluk meselesi. Markdown’da paragraf ayırmak için araya boş bir satır bırakmanız gerekiyor. Yan yana yazarsanız tek paragraf oluyor, sonra da “neden böyle öldü ya?” diye ekrana bakıp kalıyorsunuz (evet, doğru duydunuz). Saatlerce.
2. Liste içinde kod bloğu. Bir listenin — en azından ben öyle düşünüyorum — içine kod bloğu koyacaksanız, kodu girintilemeniz lazım. 4 boşluk ya da 1 tab. Bunu atlayınca liste yapısı çat diye bozuluyor, hani kağıttan kule gıbı, bir yerden sonra hepsi yamuluyor.
Küçük bir detay: 3. HTML kaçışı.
<) ya da işi güvenli tarafta tutup kod bloğu içine alın. Aksi hâlde tarayıcı bunu HTML sanıyor, sonra siz “ben bunu niye düz metin göremedim?” diye düşünüyorsunuz.
İleri Seviye İpuçları
Collapsible Sections (Açılır Kapanır Bölümler)
Bu özellik pek göze çarpmıyor. Ama README toparlarken baya iş görüyor, özellikle de belge uzadıkça insanın nefesi kesilmeye başlıyor; <details>. <summary> ile işi temiz tutabiliyorsunuz, yani ortalık dağılmıyor. Copilot Student'tan GPT-5.3-Codex Çıktı: Ne Anlama Geliyor? yazımızda bu konuya da değinmiştik.
<details>
<summary>Detayları görmek için tıklayın</summary>
İçeride istediğiniz Markdown içeriği yazabilirsiniz.
- Liste
- Tablo
- Kod bloğu
</details>Uzun kurulum notları için ideal. Troubleshooting kısmında da iyi gidiyor. FAQ tarafında işe ayrı bir rahatlık var, çünkü ana README'yi şişirmeden detay saklayabiliyorsunuz.
Evet, doğru duydunuz.
Diyagram Çizmek (Mermaid)
İtiraf edeyim, GitHub burada Mermaid syntax'ını destekliyor. Yani Markdown'ın içine direkt diyagram gömebiliyorsunuz, ilk duyunca insan "ciddi mısın?" diyor ama çalışıyor işte: (ki bu çoğu kişinin gözünden kaçıyor)
```mermaid
graph TD
A[Kullanıcı] --> B[API Gateway]
B --> C[Auth Service]
B --> D[Order Service]
```İlk gördüğümde açık konuşayım, biraz şaşırdım. Draw.io açmadan repo içinde mimarı diyagram tutmak baya kullanışlı oluyor; üstüne bir de versiyonlanıyor, yani PR'da değişikliği tek tek review edebiliyorsunuz (bu kısmı özellikle sevdim). Güzel tarafı şu: çizim ayrı yerde kalmıyor, dokümanın içinde yaşıyor.
Bak şimdi, Evet.
Emoji Shortcodes
İşte, şunu fark ettim: :rocket: 🚀, :warning: ⚠️, :white_check_mark: ✅... README'lerde ufak vurgu yapmak için fena değil. Ama dozunu kaçırmayın, yoksa belge bir anda Pokemon kartı gıbı görünmeye başlıyor; bak şimdi, biraz renk iyidir ama fazlası göz yoruyor.
İlk Adımınızı Atın
Şöyle ki, Eğer hâlâ "ben bunu deneyeyim mi acaba" diye düşünüyorsanız, bence çok büyütmeyin. Bugün açın, bir şey yapın. Şu sırayı izleyin:
- Bugün, en sevdiğiniz hobi projesinin README'sını açın.
- Üstüne bir başlık ekleyin; projenin ne yaptığını da 2 cümleyle yazın, kısa tutun ama boş da bırakmayın.
- Kurulum adımlarını numaralı liste hâlinde yazın.
- Kullanım örneğini kod bloğu içine koyun.
- Push edin, sonra GitHub'da nasıl göründüğüne bakın. — ciddi fark yaratıyor
Toplam süre: 20 dakika. Evet, bu kadar. Sonuç işe fena değil; projenize ilk kez bakan biri "bu adam işini biliyor" hissine yaklaşabiliyor. Hatta bazen küçük bir README düzeni, kodun kendisinden önce konuşuyor, garip ama doğru.
Markdown öğrenmek, açık konuşayım, teknik bir beceriden çok iletişim becerisi gıbı duruyor. Kodunuz iyi olabilir, tamam; ama anlatamıyorsanız etkisi yarıya düşüyor, hatta bazen daha da aşağı iniyor. Bu yatırımı yapın. Pişman olmazsınız.
Sıkça Sorulan Sorular
Markdown öğrenmek ne kadar sürer?
Temel söz dizimi için 1 saat fazlasıyla yeterli (evet, doğru duydunuz). İleri seviye özellikler için, yani tablolar, Mermaid, collapsible sections gıbı şeyler için 2-3 günlük düzenli kullanım yetiyor. Bence en iyi öğrenme yöntemi şu: Bir hafta boyunca neredeyse tüm notlarını Markdown'da tut, kaş hafızası kendiliğinden oluşuyor.
GitHub Markdown ile standart Markdown arasında fark var mı?
Evet, aslında GitHub Flavored Markdown (GFM) standart Markdown'a epey şey ekliyor: görev listeleri, tablolar, otomatik link tanıma, syntax highlighting, emoji shortcodes ve Mermaid diyagramları mesela. Standart Markdown'da bunlar yok. Ama temel söz dizimi tamamen aynı — GFM bilenler her yerde Markdown yazabiliyor, bu açıdan rahat.
Hmm, bunu nasıl anlatsamdı...
Markdown yerine HTML kullanmak daha mı iyi?
Genelde hayır. Markdown çok daha okunabilir, hızlı yazılıyor, bakımı da kolay (evet, doğru duydunuz). Ama Markdown'ın yetmediği durumlarda, hani karmaşık tablolar, özel stil veya video gömme gıbı şeylerde, HTML'e geçebilirsin. Zaten GitHub Markdown HTML etiketlerini destekliyor, ikisini karıştırarak kullanabiliyorsun.
VS Code'da Markdown önizleme nasıl yapılır?
VS Code'da bir .md dosyası açıkken Ctrl+Shift+V (Maç'te Cmd+Shift+V) tuşuna baş. Yan yana önizleme için Ctrl+K V yeterli. Tecrübeme göre Markdown All in Öne ve Markdown Preview Enhanced eklentilerini de kurman çok işe yarıyor, gerçekten hayatı kolaylaştırıyorlar.
README dosyasının ideal uzunluğu nedir?
Hobi projeleri için 100-200 satır yeterli. Açık kaynak bir kütüphane için 300-500 satır makul. Bunun üstüne çıkıyorsa içeriği bölüp ayrı dokümanlara taşımayı düşün. Açıkçası kimse 2000 satırlık bir README'yi okumaz, bunu kabul edelim. "Quick Start" bölümü ilk 50 satırda olmalı, gerisi zaten detay (kendi tecrübem)
Kaynaklar ve İleri Okuma
GitHub Resmî Markdown Dokümantasyonu — Tüm GFM söz dizimi burada, her zaman güncel.
The Markdown Guide — Standart Markdown için en kapsamlı kaynak, cheat sheet'leri çok faydalı.
Mermaid.js Resmî Sitesi — Diyagram çizimi için tüm söz dizimi ve örnekler burada.
Awesome README (GitHub Repo) — Dünyanın en iyi README'lerinden örnekler var, ilham almak için gerçekten harika bir kaynak (buna dikkat edin)
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
