Markdown Araçları ve Workflow: Obsidian, VS Code, Git ve MDX

Markdown'ın gücü sadece sözdiziminde değildir. Asıl değer, doğru araçlarla birleştiğinde ortaya çıkar: fikir Obsidian'da yakalanır, içerik VS Code'da düzenlenir, Git ile takip edilir, MDX ile siteye girer, Vercel ile yayınlanır.

Bu rehber Markdown workflow'unu uçtan uca kurar.

1. Araç Seçerken Ana Soru

Araç seçerken şu soruyu sor:

Bu araç yazma sürtünmesini azaltıyor mu, yoksa yeni karar yükü mü ekliyor?

Markdown araçları üç gruba ayrılabilir:

Tek araç her şeyi yapmak zorunda değildir.

2. Obsidian

Obsidian, Markdown tabanlı kişisel bilgi yönetimi için güçlüdür.

Güçlü yanları:

• Yerel Markdown dosyaları.
• Wikilink.
• Backlink.
• Graph view.
• Daily notes.
• Community plugin ekosistemi.
• Hızlı capture.

Zayıf yanları:

• Fazla plugin sistemi karmaşıklaştırabilir.
• Wikilink her yerde standart değildir.
• Görsel düzenleme beklentisi olan kullanıcılar için sade gelebilir.

Obsidian Ne İçin Kullanılmalı?

Obsidian'ı şunlar için kullan:

• fikir yakalama,
• günlük not,
• Zettelkasten,
• MOC,
• kaynak notları,
• içerik taslakları.

3. VS Code veya Cursor

VS Code/Cursor proje içindeki Markdown ve MDX dosyaları için daha uygundur.

Güçlü yanları:

• Dosya ağacı net görünür.
• Git entegrasyonu güçlüdür.
• Markdown preview vardır.
• MDX ve TypeScript projeleriyle aynı yerde çalışır.
• Arama ve toplu düzenleme hızlıdır.

Ne zaman VS Code kullanmalı?

• Site içeriği düzenlerken.
• MDX dosyası yazarken.
• Frontmatter kontrol ederken.
• Build hatası çözerken.
• Git diff incelerken.

4. Obsidian ve VS Code Birlikte Kullanılır mı?

Evet.

Önerilen ayrım:

Eğer aynı klasörü hem Obsidian hem VS Code ile açıyorsan dikkat et:

• Obsidian pluginleri ekstra dosya oluşturabilir.
• Site projesinde gereksiz .obsidian dosyalarını commit etme.
• İçerik dosyalarında standart Markdown linkleri tercih et.

5. Git ile Markdown

Markdown Git için idealdir çünkü düz metindir.

Temel Git akışı:

git status
git diff
git add content/blog/markdown-nedir-neden-kullanilir.mdx
git commit -m "Add markdown guide series"
git push

Git diff içerik değişikliklerini net gösterir.

6. GitHub'da Markdown

GitHub Markdown'ı birçok yerde kullanır:

• README.md
• issues
• pull request açıklamaları
• discussions
• wiki
• changelog

README örneği:

# Project Name

## Getting Started

\```bash
npm install
npm run dev
\```

## Scripts

| Command | Description |
| --- | --- |
| npm run dev | Local dev server |
| npm run build | Production build |

7. MDX

MDX, Markdown ile React componentlerini birleştirir.

Basit Markdown:

## Başlık

Bu normal içerik.

MDX:

## Başlık

<Callout type="info">
  Bu özel bir bilgi kutusu.
</Callout>

MDX güçlüdür ama dikkatli kullanılmalıdır. Her içerik component istemez.

CBS yaklaşımı:

• Önce düz Markdown.
• Gerekirse küçük component.
• İçeriği component mezarlığına çevirme.

8. Prettier ve Formatlama

Markdown dosyaları otomatik formatlanabilir. Ama uzun içeriklerde otomatik satır kırma bazen yazma akışını bozabilir.

Pratik yaklaşım:

• Kod projelerinde Prettier kullan.
• İçerik dosyalarında aşırı agresif formatlama yapma.
• Frontmatter girintisini temiz tut.
• Tabloları okunabilir bırak.

9. Lint ve Link Kontrolü

Büyük dokümantasyon sitelerinde Markdown lint faydalıdır.

Kontrol edilebilecek şeyler:

• kırık link,
• yanlış başlık sırası,
• boş alt text,
• fazla uzun satır,
• tekrarlayan başlık,
• geçersiz frontmatter.

Küçük MVP içerik sitesinde tüm lint sistemini hemen kurmak şart değildir. Önce build'in temiz geçmesi yeterli olabilir.

10. Markdown Yayın Workflow'u

CBS için pratik workflow:

1. Fikir Obsidian Inbox'a düşer
2. Daily review'da içerik fikrine dönüşür
3. VS Code'da MDX dosyası açılır
4. Frontmatter eklenir
5. Rehber iskeleti yazılır
6. İçerik tamamlanır
7. Internal linkler eklenir
8. npm run build
9. Vercel deploy

Bu akış basit ve sürdürülebilirdir.

11. ADHD Dostu Workflow

Markdown workflow'u ADHD dostu olacaksa şu kurallara uymalı:

Tek Capture Noktası

Fikir geldiği anda nereye yazacağını düşünmemelisin.

Taslak ve Düzenleme Ayrı Olmalı

Aynı anda hem yazıp hem mükemmelleştirmek başlatmayı zorlaştırır.

Yayın Checklist Kısa Olmalı

Checklist 40 maddeyse kullanılmaz. 8-12 madde idealdir.

Geri Dönüş Kolay Olmalı

Bir hafta kopunca yeni sistem kurmak yerine mevcut dosyaya dönmek yeterli olmalı.

12. Önerilen Araç Seti

Minimum:

Opsiyonel:

13. Dosya Akışı Örneği

Obsidian/
└── Inbox.md
    ↓
Obsidian/
└── Notes/Permanent/markdown-duz-metin.md
    ↓
cbs-next/
└── content/blog/markdown-nedir-neden-kullanilir.mdx
    ↓
Next.js build
    ↓
Vercel production

Bu akış fikri kaybetmeden yayına taşır.

14. Build Hataları

Markdown/MDX içeriklerinde sık build hataları:

Geçersiz YAML

tldr:
  - Problem: iki nokta yüzünden YAML bozulabilir

Çözüm:

tldr:
  - "Problem: iki nokta yüzünden YAML bozulabilir"

Kırık Link

Yanlış:

[Rehber](/rehberler/yanlis-slug)

Doğru slug'ı kontrol et.

MDX İçinde JSX Karakteri

MDX bazı karakterleri JSX gibi yorumlayabilir. Düz Markdown yazarken gereksiz {} ve HTML kullanma.

15. Yayın Öncesi Terminal Akışı

npm run build

Build başarılıysa:

vercel deploy . --prod -y

Bu repo için build, statik sayfaların gerçekten üretildiğini doğrular.

16. Markdown Workflow Checklist

## Markdown Workflow Checklist

- [ ] Fikir Inbox'a yakalandı
- [ ] Taslak ayrı dosyada çıkarıldı
- [ ] Frontmatter tamamlandı
- [ ] Başlık hiyerarşisi temiz
- [ ] İç linkler eklendi
- [ ] Related rehberler bağlandı
- [ ] Build başarılı
- [ ] Deploy tamamlandı

17. Ne Zaman Yeni Araç Eklememeli?

Şu durumlarda yeni araç ekleme:

• Sorun aslında içerik yazmamaksa.
• Mevcut araç yeterliyse.
• Yeni araç sadece estetik heyecan yaratıyorsa.
• Workflow'u hızlandırmak yerine karar yükü ekliyorsa.

Markdown'ın gücü sadeliktir. Araç seti bu sadeliği bozuyorsa geri çekil.

18. Sonuç

Markdown workflow'u iyi kurulduğunda fikirden yayına giden yol kısalır.

CBS için pratik hedef:

Fikir hızlı yakalansın.
Taslak kolay yazılsın.
Dosya temiz dursun.
Build geçsin.
Yayın hızlı çıksın.

Markdown tam olarak bu akış için güçlü bir zemindir.