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 yine .astro layout’tur.

---

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 };

• blog → koleksiyon adı
• glob → src/content/blog/ altındaki tüm .md ve .mdx dosyaları
• schema → frontmatter kuralları

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ı sayfası
        ↓
BaseLayout.astro (kabuk, Fix UI, Tailwind)

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

---

Ne İşe Yarar?

Kullanım	Dosya	Açıklama
Blog yazısı	src/content/blog/yazi.mdx	Uzun metin, tarih, açıklama
Sadece Markdown	.md	JSX gerekmiyorsa yeterli
Bileşenli içerik	.mdx	<Card>, <Button> vb. gömülebilir

Falcon’da blog Content Collection (src/content/blog/) ile dosya tabanlıdır; ekip veya testimonial koleksiyonu yoktur. MDX bu zincirin yazı formatıdır.

Bu rehber sitesi (astro-docs) ayrı bir projedir; Falcon repo’sunda src/content/docs/ koleksiyonu yoktur.

---

Nasıl Kullanılır?

Yeni Blog Yazısı

1. src/content/blog/yeni-yazi.mdx oluştur
2. Frontmatter doldur (title, description, pubDate)
3. Gövdeyi Markdown ile yaz
4. Route sayfaları (src/pages/blog/) yazıyı /blog altında listeler

---

Blog Sayfaları (Route)

MDX içerikleri src/content/blog/ altında durur; sitede görünmesi için route gerekir:

Sayfa	Dosya	URL
Liste	src/pages/blog/index.astro	/blog
Tekil yazı	src/pages/blog/[...slug].astro	/blog/{id}/

Liste getCollection('blog') ile yazıları alır; tekil sayfa render(post) ile MDX gövdesini <Content /> olarak basar.

Çok dilli blog: EN öneksiz (/blog/...), diğer diller /tr/blog/..., /de/blog/..., /fr/blog/... — ayrıntı Çoklu Dil Kullanımı.

Liste Sayfası

src/pages/blog/index.astro:

---
import { getCollection } from 'astro:content';
import BaseLayout from '@/layouts/BaseLayout.astro';

const posts = (await getCollection('blog')).sort(
  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
);
---

<BaseLayout title="Blog">
  <main class="fix-section">
    <div class="fix-container">
      <h1 class="fix-type-h1">Blog</h1>
      <ul>
        {posts.map((post) => (
          <li>
            <a href={`/blog/${post.id}/`}>{post.data.title}</a>
          </li>
        ))}
      </ul>
    </div>
  </main>
</BaseLayout>

Tekil Yazı

src/pages/blog/[...slug].astro:

---
import { getCollection, render } from 'astro:content';
import BaseLayout from '@/layouts/BaseLayout.astro';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.id },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await render(post);
---

<BaseLayout title={post.data.title} description={post.data.description}>
  <article class="fix-section">
    <div class="fix-container">
      <h1 class="fix-type-h1">{post.data.title}</h1>
      <article class="fix-prose">
        <Content />
      </article>
    </div>
  </article>
</BaseLayout>

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

welcome.mdx içinde:

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

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

Astro bileşenleri doğrudan import edilir. React bileşeni için client:* direktifi gerekir (React rehberine bakın).

---

Fix UI Ve Tailwind Ile İlişki

• MDX dosyası stil içermez; görünüm layout ve global CSS’ten gelir.
• Liste/ detay sayfasında fix-section, fix-container, Button, Card kullanılır.
• Uzun yazı gövdesi fix-prose sarmalayıcıdan gelir — Yazı Stilleri.

---

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 (önce şemayı güncelle)
Kabuk için .astro 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()
• src/pages/blog/index.astro ve [...slug].astro mevcut

Tarayıcıda /blog ve tekil yazı URL’si (/blog/{id}/) açılmalı.

---

Özet Cümle

MDX = içerik formatı; Content Collections = organize katman; route = /blog ve /blog/{id}/ (diller için önekli mirror’lar). Kurulum: @astrojs/mdx + mdx() + content.config.ts + src/content/blog/ + src/pages/blog/. Kullanım: yeni .mdx + getCollection / render.