MDX Kullanımı Ve Blog URL

Bu belge, Falcon’da MDX ve Content Collections’ın neden eklendiğini, nasıl kurulduğunu, blog URL’lerinin nasıl üretildiğini ve ne zaman nasıl kullanılacağını anlatır.

---

MDX Nedir?

MDX, Markdown’a JSX eklemenizi sağlar. Normal .md dosyasında başlık, liste, link yazarsınız; .mdx dosyasında gerektiğinde Astro/React bileşeni de kullanırsınız.

Falcon’da MDX şu amaçla kuruldu:

• Blog, rehber, uzun metin içeriklerini koddan ayırmak
• İçeriği src/content/ altında toplamak (build zamanında okunur)
• Frontmatter alanlarını şema ile doğrulamak (eksik title vb. build’de hata verir)
• İçeriği Git + MDX ile yönetmek (harici CMS planlanmıyor)

MDX, Fix UI veya Tailwind’in yerine geçmez. Yalnızca içerik formatıdır; sayfa kabuğu .astro layout + BlogPostView ile gelir.

---

Ne Yaptık? (Kurulum)

1. Paket

npm install @astrojs/mdx

2. astro.config.mjs

import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [react(), mdx()],
});

react() zaten vardı; MDX içinde React bileşeni kullanacaksanız ikisi birlikte kalır.

3. src/content.config.ts

Content Collections tanımı:

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
  }),
});

export const collections = { blog };

4. Örnek İçerik

src/content/blog/welcome.mdx:

---
title: Welcome to MDX
description: Example blog entry
pubDate: 2026-05-18
---

# Welcome to MDX

Markdown metni burada.

---

Nasıl Çalışır?

welcome.mdx (içerik + frontmatter)
        ↓
content.config.ts (şema doğrular)
        ↓
getCollection('blog')  →  liste sayfası
render(entry)          →  tekil yazı (BlogPostView)
        ↓
BaseLayout.astro (kabuk) + PageShell + prose

• İçerik build sırasında okunur; veritabanı yoktur.
• astro:content modülü tipleri otomatik üretir (.astro/content.d.ts).

---

Blog Sayfaları (Route)

Sayfa	Dosya	URL
Liste	src/pages/blog/index.astro (+ locale mirror’lar)	/blog, /tr/blog, …
Tekil yazı	src/pages/blog/[...slug].astro	/blog/{id}/

Liste ve detay BlogIndexView / BlogPostView bileşenlerini kullanır; tekil yazıda MDX gövdesi prose ile basılır.

---

BlogPostView Örneği

src/components/blog/BlogPostView.astro (özet):

---
import PageShell from '@/components/layout/PageShell.astro';
const { Content } = await render(post);
---

<PageShell narrow class="flex flex-col gap-8">
  <h1 class="m-0 text-3xl font-extrabold sm:text-4xl">{title}</h1>
  <p class="text-xl text-muted-foreground">{description}</p>
  <article class:list={['prose max-w-none dark:prose-invert', /* prose-* modifier’lar */]}>
    <Content />
  </article>
</PageShell>

• Başlık / açıklama → Tailwind utility
• Gövde → @tailwindcss/typography (prose)
• Layout → PageShell

Ayrıntı: Yazı Stilleri.

---

MDX Içinde Bileşen (İsteğe Bağlı)

import Button from '@/components/ui/Button.astro';

<Button variant="primary">CTA</Button>

React bileşeni için client:* direktifi gerekir — React Kullanımı.

---

Fix UI Ve Tailwind Ile İlişki

• MDX dosyası stil içermez; görünüm BlogPostView ve global CSS’ten gelir.
• Liste sayfasında PageShell, Button, Card kullanılabilir.
• Uzun yazı gövdesi prose sarmalayıcıdan gelir — fix-prose kullanılmaz.

---

Kurallar

Yap	Yapma
İçeriği src/content/ altında tut	Blog metnini pages/ içine göm
Frontmatter’ı şemaya uygun yaz	Şemada olmayan alanı keyfi ekle
Kabuk için BlogPostView / layout	Her yazı için ayrı tam HTML sayfa
.md basit metin, .mdx bileşen gerekiyorsa	Her şeyi .mdx yapma

---

Doğrulama

• npm run build hatasız
• src/content/blog/*.mdx mevcut
• src/content.config.ts içinde blog koleksiyonu tanımlı
• astro.config.mjs içinde mdx()
• /blog ve tekil yazı URL’si açılmalı

---

Özet

MDX = içerik formatı; Content Collections = organize katman; görünüm = BlogPostView + PageShell + prose. Kurulum: @astrojs/mdx + content.config.ts + src/content/blog/ + route mirror’lar.