Nuxt 4 ve Content 3 ile Markdown blog kurulumu

Bu blogda yazıları Markdown dosyalarında tutuyorum. Başlık, açıklama ve tarih dosyanın başında; yazının kendisi hemen altında. Nuxt Content bu dosyaları okuyup sayfalarda sorgulayabildiğim bir koleksiyona dönüştürüyor.

Aşağıdaki örnekleri 12 Ekim 2026'da Nuxt 4 ve Content 3'e göre güncelledim. Amaç, yazı listesi ve detay sayfası çalışan küçük bir blog kurmak.

Projeyi hazırlama

Node 24 ile yeni projeyi oluşturup Content modülünü ekleyebilirsin:

npm create nuxt@latest my-blog
cd my-blog
npx nuxt module add content

nuxt.config.ts içinde modülün bulunduğunu kontrol et. Bu örnekte Node'un yerleşik SQLite bağlantısını kullanıyorum:

export default defineNuxtConfig({
  modules: ['@nuxt/content'],
  content: {
    experimental: { sqliteConnector: 'native' }
  }
})

Nuxt 4'te sayfalar app/pages/, yazılar ise projenin kökündeki content/ klasöründe duruyor. app/app.vue dosyasında başlangıç ekranı varsa onu <NuxtPage /> ile değiştir:

<template>
  <NuxtPage />
</template>

Yazı koleksiyonunu tanımlama

Köke content.config.ts dosyasını ekle:

import { defineCollection, defineContentConfig, z } from '@nuxt/content'

export default defineContentConfig({
  collections: {
    blog: defineCollection({
      type: 'page',
      source: 'blog/**/*.md',
      schema: z.object({
        date: z.string()
      })
    })
  }
})

Bu koleksiyon content/blog/ altındaki Markdown dosyalarını okuyor. Sayfa türündeki koleksiyonda başlık, açıklama ve yol alanları hazır geliyor; burada tarih alanını ayrıca tanımladım.

İlk yazı için content/blog/ilk-yazi.md oluştur:

---
title: 'İlk yazım'
description: 'Markdown ile tuttuğum ilk blog notu.'
date: '2026-10-12'
---

Buraya yazının girişini ekleyebilirim.

## İlk notlar

Markdown ile bağlantı, liste ve kod blokları kullanabilirim.

Başlığı sayfa şablonu göstereceği için gövdede tekrar bir H1 yazmıyorum.

Yazıları listeleme

app/pages/blog/index.vue dosyası /blog adresini oluşturur:

<script setup lang="ts">
const { data: posts } = await useAsyncData('blog-list', () =>
  queryCollection('blog')
    .order('date', 'DESC')
    .select('path', 'title', 'description')
    .all()
)
</script>

<template>
  <main>
    <h1>Yazılar</h1>
    <article v-for="post in posts" :key="post.path">
      <h2><NuxtLink :to="post.path">{{ post.title }}</NuxtLink></h2>
      <p>{{ post.description }}</p>
    </article>
  </main>
</template>

Content 3'te sorgu için queryCollection kullanılıyor. Eski örneklerdeki queryContent, _path ve findOne kullanımları Content 2'ye ait.

Yazının tamamını açma

app/pages/blog/[slug].vue, dosya adına göre yazıyı açar. Örneğin ilk dosyamızın adresi /blog/ilk-yazi olur:

<script setup lang="ts">
const route = useRoute()
const { data: post } = await useAsyncData(
  () => 'blog-' + route.path,
  () => queryCollection('blog').path(route.path).first()
)

if (!post.value) {
  throw createError({ statusCode: 404, statusMessage: 'Yazı bulunamadı' })
}

useSeoMeta({
  title: () => post.value?.title,
  description: () => post.value?.description,
  ogTitle: () => post.value?.title,
  ogDescription: () => post.value?.description,
  ogType: 'article'
})
</script>

<template>
  <main v-if="post">
    <h1>{{ post.title }}</h1>
    <p>{{ post.description }}</p>
    <ContentRenderer :value="post" />
  </main>
</template>

ContentRenderer yazı gövdesini ekrana getiriyor. Yeni yazı eklemek için aynı koleksiyona bir Markdown dosyası daha koymak yeterli.

Çalıştırma ve yayın

npm run dev ile geliştirme sunucusunu açıp /blog adresini kontrol edebilirsin. Yayından önce npm run build ve ardından npm run preview ile üretim çıktısını dene.

Bu örnekte başlık ve açıklama etiketleri var. Sitemap, canonical adres ve paylaşım görseli ayrıca yapılandırılmalı; yalnızca Content modülünü eklemek bunların tamamını hazırlamıyor. Benim portfolyomda sitemap için ayrı bir modül kullanılıyor.

Başvurduğum belgeler: Nuxt proje oluşturma, Content koleksiyonları, koleksiyon sorguları ve Content 3 geçiş rehberi.