GitHub README İçin Markdown İpuçları: Profesyonel bir dosya nasıl yazılır
Bir açık kaynak projesinin ilk izlenimi neredeyse her zaman README.md dosyasıdır. Aynı temel markdown sözdizimiyle yazılsa da, GitHub'a özgü birkaç teknik — rozet, katlanabilir bölüm, dil etiketli kod bloğu — sıradan bir dosyayı profesyonel görünen bir projeye dönüştürür. Bu rehberde açık kaynak projelerin en çok kullandığı 10 pratik ipucunu örneklerle inceliyoruz.
GitHub markdown ipuçları nedir?
<details> ile katlanabilir bölümler, dil etiketli kod blokları için otomatik sözdizimi vurgusu ve başlıklardan otomatik üretilen çapa (anchor) bağlantıları. Bu ipuçları temel markdown bilginize eklenen, GitHub'a özgü katmandır.
Bu tekniklerin hiçbiri "gizli" değildir — hepsi GFM'in izin verdiği ham HTML ve görsel sözdizimi kombinasyonlarıdır. Farkı yaratan, bunları doğru yerde ve doğru sırada kullanmaktır. Önce temel markdown sözdizimine hakim değilseniz "Markdown Nedir, Nasıl Yazılır?" rehberimizle başlamanızı öneririz.
1-2. Rozet (badge) ekleme
. shields.io gibi servisler build durumu, sürüm numarası, lisans veya indirme sayısı gibi bilgileri anlık olarak bir görsele dönüştürür; siz sadece o görsel URL'sini görsel sözdiziminde kullanırsınız. Genellikle birden fazla rozet üst üste, başlığın hemen altına dizilir.
  
İpucu 2: Rozeti tıklanabilir yapmak için bağlantı sözdizimiyle sarmalayın: [](hedef-url). Örneğin bir "Build" rozetini CI/CD panelinize, "Sürüm" rozetini ise sürüm notları sayfasına yönlendirebilirsiniz — kullanıcı rozete tıkladığında ilgili detay sayfasına gider.
3-4. Dil etiketli kod bloğu ve klavye kısayolu
```bash, ```python, ```json) GitHub o dile özel sözdizimi vurgusu uygular ve kod bloğunun sağ üst köşesinde otomatik bir kopyalama butonu görünür. Dil belirtilmezse kod düz metin renginde kalır.
```bash npm install proje-adi npm run build ```
İpucu 4: Klavye kısayolu belirtmek için <kbd> HTML etiketi kullanılabilir — GitHub bunu bir tuş görseline benzer şekilde render eder: <kbd>Ctrl</kbd> + <kbd>C</kbd>. Kurulum adımlarında komut satırı kodunu her zaman dil etiketiyle yazmak, README'nizi teknik olarak daha güvenilir gösterir.
Rozet ve kod bloklarını şimdi deneyin
Yukarıdaki örnekleri kopyalayıp editöre yapıştırın, kendi README taslağınızda nasıl göründüğünü canlı izleyin.
Markdown Önizleyiciyi Aç →5-6. Katlanabilir bölüm ve otomatik içindekiler
<details><summary> etiketleriyle sarmalayarak varsayılan olarak kapalı, tıklanınca açılan bir bölüm oluşturabilirsiniz. GitHub markdown içinde temel HTML etiketlerine izin verdiği için bu doğrudan çalışır.
<details> <summary>Kurulum sırasında hata mı aldınız? Tıklayın</summary> 1. Node.js sürümünüzü kontrol edin (18+ gerekli) 2. `node_modules` klasörünü silip yeniden yükleyin 3. Hâlâ sorun varsa bir issue açın </details>
İpucu 6: GitHub, her ## ve ### başlığından otomatik olarak bir çapa (anchor) kimliği üretir — başlığı küçük harfe çevirip boşlukları tire yapar. Bu yüzden kendi içindekiler listenizi [Kurulum](#kurulum) gibi bağlantılarla elle yazabilirsiniz; ekstra bir eklenti gerekmez. Uzun README'lerde (300+ satır) bu içindekiler listesi okunabilirliği ciddi ölçüde artırır.
Katlanabilir bölüm içinde markdown kullanmak
Dikkat: <details> içinde markdown'ın (liste, kod bloğu, kalın metin) doğru render edilmesi için etiketin hemen altına boş bir satır bırakmanız gerekir. Boş satır bırakmazsanız GitHub içeriği ham metin olarak, biçimlendirmeden gösterebilir.
7-8. Görsel boyutlandırma ve tema-duyarlı görsel
 sözdizimi görsel boyutunu kontrol etmenize izin vermez. Boyutu ayarlamak için ham HTML <img src="url" width="480"> etiketi kullanılır. Açık/koyu temaya göre farklı görsel göstermek için ise GitHub'ın <picture> + prefers-color-scheme desteğinden yararlanılır.
<img src="ekran-goruntusu.png" width="480" alt="Uygulama arayüzü">
İpucu 8: Logo gibi görselleri koyu ve açık GitHub temasında da okunaklı göstermek için <picture> etiketiyle iki farklı kaynak tanımlayabilirsiniz — GitHub, kullanıcının aktif temasına göre doğru görseli otomatik seçer. Bu, özellikle şeffaf arka planlı logo dosyalarında görünürlük sorununu tamamen çözer.
9-10. İskelet yapı ve lisans bölümü
Aşağıdaki tablo, üzerine oturacağınız temel bir README iskeletinin bölümlerini ve amacını özetler — projenizin büyüklüğüne göre bazı bölümleri çıkarabilir veya birleştirebilirsiniz.
| Sıra | Bölüm | Amaç |
|---|---|---|
| 1 | Başlık + rozetler | Proje adı ve anlık güven sinyalleri |
| 2 | Tek cümlelik açıklama | Ziyaretçi 5 saniyede ne olduğunu anlar |
| 3 | Kurulum kod bloğu | Kopyala-yapıştır ile çalışır hale getirme |
| 4 | Kullanım örneği | Temel senaryoyu gösteren kısa kod |
| 5 | İçindekiler (uzun README'lerde) | Hızlı gezinme |
| 6 | SSS (katlanabilir) | Sayfayı uzatmadan detay sunma |
| 7 | Katkıda bulunma | Topluluk katkısını teşvik etme |
| 8 | Lisans | Yasal kullanım koşulunu netleştirme |
Kaynak: GitHub Docs, "About READMEs" ve açık kaynak topluluk pratikleri.
Lisans bölümünü eklerken tam metni README'ye gömmek yerine ayrı bir LICENSE dosyasına bağlantı vermek yaygın pratiktir: Bu proje [MIT Lisansı](LICENSE) ile lisanslanmıştır. Tablo yazımını henüz öğrenmediyseniz kurulum matrisi veya karşılaştırma tabloları için "Markdown ile Tablo Nasıl Oluşturulur?" rehberimize göz atın; temel sözdizimini tazelemek isterseniz "Markdown Nedir, Nasıl Yazılır?" yazımız başlangıç noktanız olabilir.