Markdown Dosya Mimarisi: Frontmatter, Metadata ve Klasör Yapısı

Markdown dosyası yazmak kolaydır. Zor olan, yüzlerce Markdown dosyası biriktiğinde hâlâ bulabilmek, düzenleyebilmek ve yayınlayabilmektir.

Bu rehber dosya mimarisine odaklanır: klasör yapısı, dosya adı, slug, frontmatter, metadata ve arşiv.

1. Dosya Mimarisi Neden Önemli?

Markdown düz metindir ama düz metin olması otomatik olarak düzenli olduğu anlamına gelmez.

Kötü mimari:

notes/
├── yeni.md
├── fikirler.md
├── markdown.md
├── blog-son.md
├── blog-son-final.md
└── gerçekten-final.md

İyi mimari:

content/
├── blog/
│   ├── markdown-nedir-neden-kullanilir.mdx
│   └── markdown-sozdizimi-rehberi.mdx
├── glossary/
│   ├── markdown.mdx
│   └── frontmatter.mdx
└── drafts/
    └── markdown-yeni-fikirler.md

Mimari, karar yükünü azaltır.

2. Klasör Yapısı Nasıl Kurulur?

Klasör yapısı kullanım amacına göre kurulmalı.

İçerik sitesi için:

content/
├── blog/
├── glossary/
├── guides/
├── pages/
└── drafts/

Obsidian için:

Vault/
├── 00 Inbox/
├── 01 Daily/
├── 02 Notes/
├── 03 Projects/
├── 04 Resources/
└── 99 Archive/

Kod projesi için:

docs/
├── getting-started.md
├── architecture.md
├── api.md
└── changelog.md

Tek doğru yapı yoktur. Doğru yapı, dosyayı ne için kullandığına göre değişir.

3. Az Klasör Kuralı

Klasör sayısını düşük tut.

Çok derin yapı:

Notes/
└── Productivity/
    └── Markdown/
        └── Blog/
            └── SEO/
                └── Drafts/

Daha iyi:

Notes/
├── Permanent/
├── Projects/
└── Resources/

Derin klasörler ADHD için saklanma alanına dönüşebilir. Dosya doğru klasöre girmediği için hiç yazılmayabilir.

4. Dosya Adı Nasıl Yazılır?

Dosya adı:

• küçük harfli,
• kısa,
• açıklayıcı,
• boşluksuz,
• Türkçe karakterden arındırılmış,
• URL dostu olmalı.

İyi:

markdown-sozdizimi-rehberi.mdx
markdown-ile-not-alma-sistemi.mdx
frontmatter-metadata-rehberi.mdx

Zayıf:

Markdown Sözdizimi Rehberi Final.mdx
markdown rehberi yeni son.mdx
Untitled 12.md

5. Slug Nedir?

Slug, sayfanın URL'deki adıdır.

Dosya:

markdown-sozdizimi-rehberi.mdx

URL:

/rehberler/markdown-sozdizimi-rehberi

Slug seçerken:

• kısa tut,
• ana konuyu taşısın,
• gereksiz kelime kullanma,
• mümkünse değişmeyecek şekilde seç.

Slug değişirse eski linkler kırılabilir.

6. Frontmatter Nedir?

Frontmatter dosyanın üst kısmındaki metadata alanıdır.

---
title: "Markdown Dosya Mimarisi"
date: "2026-05-07"
tag: "Sistemler ve Araçlar"
---

Bu alan yazının içeriği değil, yazı hakkında bilgidir.

7. CBS Rehber Frontmatter Şablonu

CBS rehberleri için iyi başlangıç:

---
title: "Rehber Başlığı"
subtitle: "Rehberin bir cümlelik açıklaması."
date: "2026-05-07"
dateModified: "2026-05-07"
readTime: "18 dk okuma"
author: "Chaotic Brain Studio"
tag: "Sistemler ve Araçlar"
series: "markdown-rehberi"
seriesTitle: "Markdown Rehberi"
seriesOrder: 5
tool: "markdown"
excerpt: "Arama ve kart görünümü için kısa açıklama."
tldr:
  - "Birinci ana fikir."
  - "İkinci ana fikir."
  - "Üçüncü ana fikir."
related:
  - title: "İlgili Rehber"
    slug: "ilgili-rehber"
    tag: "Sistemler ve Araçlar"
    tagColor: "#7c3aed"
---

8. Metadata Alanları Ne İşe Yarar?

Bu alanlar doğruysa sayfa otomatik olarak daha iyi çalışır.

9. YAML Hatalarından Kaçınma

Frontmatter YAML formatındadır. YAML hassastır.

İki Nokta Hatası

Riskli:

tldr:
  - Problem: Dosya mimarisi karışıyor

Güvenli:

tldr:
  - "Problem: Dosya mimarisi karışıyor"

Girinti Hatası

Riskli:

related:
- title: "Rehber"
slug: "rehber"

Güvenli:

related:
  - title: "Rehber"
    slug: "rehber"

Tırnak Kullanımı

Metin alanlarında tırnak kullanmak güvenlidir:

title: "Markdown Dosya Mimarisi"

10. Draft ve Published Ayrımı

İçerik sisteminde taslak ve yayınlanmış içerik ayrılmalı.

Basit yapı:

content/
├── blog/
└── drafts/

Alternatif:

---
title: "Taslak Yazı"
draft: true
---

Hangi yöntemi kullanacağın site sistemine bağlıdır. Basit projelerde ayrı drafts klasörü daha anlaşılır olabilir.

11. İçerik Arşivi

Eski içerikleri silmek yerine arşivlemek bazen daha doğru olur.

content/
├── blog/
├── drafts/
└── archive/

Arşiv şunlar için kullanılabilir:

• yayınlanmayacak eski taslaklar,
• güncelliğini yitirmiş içerikler,
• başka ürüne taşınan metinler,
• yeniden yazılacak rehberler.

12. Görsel Dosya Mimarisi

Markdown içindeki görseller için görsel klasörü de düzenli olmalı.

public/
└── markdown/
    ├── markdown-editor.png
    ├── obsidian-vault.png
    └── frontmatter-example.png

Görsel dosya adı:

frontmatter-example.png

Zayıf:

Screenshot 2026-05-07 at 14.22.10.png

13. Versiyon Kontrolü

Markdown Git ile iyi çalışır.

Değişiklik farkı okunabilir:

- Markdown sadece not almak için kullanılır.
+ Markdown not alma, dokümantasyon ve içerik üretimi için kullanılabilir.

Bu yüzden blog, dokümantasyon ve rehber içerikleri için Git tabanlı akış mantıklıdır.

14. İçerik Dosyaları İçin Kontrol Listesi

## Dosya Kontrol Listesi

- [ ] Dosya adı URL dostu mu?
- [ ] Slug kısa ve anlaşılır mı?
- [ ] Frontmatter eksiksiz mi?
- [ ] Date ve dateModified doğru mu?
- [ ] Excerpt kartta iyi görünecek kadar net mi?
- [ ] Related linkler var mı?
- [ ] Görsel dosya yolları doğru mu?
- [ ] İçerik doğru klasörde mi?

15. CBS İçin Önerilen İçerik Mimarisi

Bu repo zaten şu mantığa yakın çalışıyor:

content/
├── blog/
└── glossary/

app/
├── rehberler/
├── blog/
└── sozluk/

Bu iyi bir ayrım:

• content/blog içerik kaynağıdır.
• /rehberler aynı içeriği rehber yüzeyiyle sunar.
• /blog aynı içeriği blog yüzeyiyle sunabilir.
• content/glossary sözlük maddelerini taşır.

İçerik tek yerde durur, farklı sayfa yüzeylerinde kullanılır.

16. Minimum Mimari

Yeni bir Markdown içerik sistemi kuruyorsan şununla başla:

content/
├── posts/
├── glossary/
├── drafts/
└── assets/

Sonra ihtiyaç oldukça genişlet.

17. Sonraki Adım

Bir sonraki bölümde Markdown workflow'unu araçlarla birleştireceğiz: Obsidian, VS Code, Git, GitHub, MDX, Prettier, lint ve yayın akışı.