Nuxt Content: Markdown basierte Seiten richtig aufbauen

1. Was Nuxt Content wirklich löst

Nuxt Content ist ein offizielles Nuxt Modul, das Markdown, YAML, JSON und CSV Dateien aus dem Projektverzeichnis in eine abfragbare Datenschicht überführt. Statt Inhalte in einer externen Datenbank oder einem Headless CMS zu verwalten, liegen sie als Textdateien direkt im Repository, versioniert mit Git, review fähig per Pull Request und ohne zusätzliche Infrastruktur. Für Dokumentationsseiten, technische Blogs und Marketing Landingpages ist das oft die pragmatischere Wahl als ein vollwertiges CMS mit eigener Datenbank und Adminoberfläche.

Der Kern von Nuxt Content ist eine Build Zeit Pipeline, die alle Dateien in einem konfigurierten Verzeichnis, meist content/, einliest, parst und in eine SQLite Datenbank überführt, die zur Laufzeit abgefragt wird. Das unterscheidet Nuxt Content von einem simplen Markdown Renderer: Man bekommt einen echten Query Builder mit Filtern, Sortierung und Volltextsuche, nicht nur eine Funktion, die Markdown in HTML umwandelt. Genau diese Kombination aus Dateibasiertem Arbeiten und datenbankartiger Abfrage macht Nuxt Content für größere Projekte interessant.

Ein praktisches Beispiel: Ein Team pflegt eine Produktdokumentation mit fünfzig Seiten in mehreren Kategorien. Ohne Nuxt Content müsste jede Seite manuell verlinkt, jede Navigation von Hand gepflegt und jede Änderung am Aufbau in mehreren Dateien nachgezogen werden. Mit Nuxt Content generiert eine einzige Katalog Abfrage die komplette Navigation aus der Verzeichnisstruktur, inklusive Sortierung nach Frontmatter Feldern und automatischer Breadcrumb Erzeugung.

2. Installation und Verzeichnisstruktur

Die Installation von Nuxt Content erfolgt über den Nuxt Modul Mechanismus. Nach der Installation muss lediglich das Modul in der nuxt.config.ts eingetragen werden, danach erkennt Nuxt automatisch das Verzeichnis content/ im Projektroot. Innerhalb dieses Verzeichnisses spiegelt die Ordnerstruktur direkt die spätere URL Struktur wider, ein Muster, das man von dateibasiertem Routing in Nuxt Pages bereits kennt und das Nuxt Content konsequent weiterführt.

Wichtig ist die Namenskonvention für die Reihenfolge von Navigationseinträgen: Präfixe wie 1.einfuehrung.md oder 2.installation.md steuern die Sortierung in generierten Navigationsbäumen, ohne dass diese Nummern in der finalen URL erscheinen. Nuxt Content entfernt diese Präfixe automatisch beim Erzeugen der Route. Diese Konvention erspart ein separates Sortierfeld in jeder Datei und hält die Struktur direkt im Dateisystem sichtbar, was besonders bei der Zusammenarbeit im Team einen echten Vorteil bringt.

# Install Nuxt Content module
npx nuxi module add content

# Resulting directory structure for a documentation site
content/
├── 1.getting-started/
│   ├── 1.introduction.md
│   └── 2.installation.md
├── 2.guides/
│   ├── 1.routing.md
│   └── 2.data-fetching.md
└── index.md

# nuxt.config.ts registration
export default defineNuxtConfig({
  modules: ['@nuxt/content'],
  content: {
    // Optional: configure markdown highlighter theme
    highlight: {
      theme: 'github-dark'
    }
  }
})

3. Frontmatter und Metadaten in Markdown

Jede Markdown Datei in Nuxt Content kann am Anfang einen YAML Frontmatter Block enthalten, der strukturierte Metadaten neben dem eigentlichen Text speichert. Titel, Beschreibung, Veröffentlichungsdatum, Autor und beliebige eigene Felder landen dort und stehen im Query Builder als abfragbare Spalten zur Verfügung. Das ist der entscheidende Unterschied zu reinem Markdown ohne Frontmatter: Man kann nach diesen Feldern filtern, sortieren und sie in Übersichtsseiten anzeigen, ohne den Fließtext parsen zu müssen.

Für SEO relevante Felder wie description oder ein eigenes ogImage Feld lohnt sich eine feste Konvention über alle Dateien hinweg, damit die spätere Meta Tag Generierung in Nuxt konsistent bleibt. In größeren Projekten empfiehlt sich zusätzlich ein Schema, das Frontmatter Felder validiert. Nuxt Content unterstützt dafür Zod basierte Collection Definitionen, die genau festlegen, welche Felder eine Datei haben muss und welchen Typ sie tragen, was Tippfehler in Feldnamen frühzeitig als Build Fehler statt als stillen Laufzeitfehler sichtbar macht.

---
title: "Nuxt Content Grundlagen"
description: "Wie Frontmatter und Markdown zusammenspielen"
date: 2026-07-14
author: "Mironsoft Redaktion"
tags: ["nuxt", "content", "markdown"]
draft: false
---

## Einleitung

Der eigentliche Markdown Text beginnt nach dem Frontmatter Block.
Alle Felder oberhalb sind über den Query Builder abfragbar,
ohne dass der Fliesstext geparst werden muss.

4. Der Query Builder: Inhalte laden und filtern

Der Query Builder ist das Herzstück von Nuxt Content für alle dynamischen Anwendungsfälle. Mit dem Composable queryCollection lassen sich Inhalte nach Pfad, Frontmatter Feldern oder Volltext filtern, sortieren und paginieren, direkt innerhalb einer Vue Komponente oder eines Server Endpunkts. Diese Abfragen laufen zur Build Zeit gegen die generierte SQLite Datenbank und sind deutlich schneller als das Parsen von Markdown Dateien zur Laufzeit bei jedem Seitenaufruf.

Ein typisches Muster ist eine Blog Übersichtsseite, die alle Artikel eines bestimmten Tags lädt, nach Datum absteigend sortiert und die ersten zehn Einträge anzeigt. Ohne Nuxt Content müsste man dafür entweder eine externe API anbinden oder selbst eine Indexierungslogik über alle Markdown Dateien schreiben. Der Query Builder von Nuxt Content übernimmt genau diese Aufgabe deklarativ und typsicher, inklusive automatischer TypeScript Typen aus der Collection Definition.

// composables/useBlogPosts.ts
export function useBlogPosts(tag: string) {
  // Query the content collection with filtering, sorting and pagination
  return useAsyncData(`blog-${tag}`, () =>
    queryCollection('blog')
      .where('tags', 'LIKE', `%${tag}%`)
      .where('draft', '=', false)
      .order('date', 'DESC')
      .limit(10)
      .all()
  )
}

// Usage inside a Vue component <script setup>
const { data: posts } = await useBlogPosts('nuxt')

5. MDC Syntax: Vue Komponenten in Markdown

Ein Alleinstellungsmerkmal von Nuxt Content ist die MDC Syntax, kurz für Markdown Components. Sie erlaubt es, echte Vue Komponenten direkt innerhalb von Markdown Text zu platzieren, inklusive Props und sogar verschachteltem Slot Inhalt. Ein Redakteur kann so eine interaktive Callout Box, ein Tab Widget oder eine Code Vorschau mitten im Fließtext einbetten, ohne dass ein Entwickler dafür manuell HTML schreiben muss.

Technisch funktioniert MDC über eine spezielle Doppelpunkt Notation, die Nuxt Content beim Parsen erkennt und in eine Vue Komponente mit den angegebenen Props auflöst. Wichtig für die Praxis: Jede Komponente, die per MDC verwendet werden soll, muss vorher als globale Komponente registriert oder im Verzeichnis components/content/ abgelegt werden, damit Nuxt Content sie beim Rendern findet. Diese Konvention trennt sauber zwischen normalen Anwendungskomponenten und den für Redakteure freigegebenen Content Komponenten.

## Deployment Hinweis

::alert{type="warning"}
Vor jedem Production Deployment muss die Umgebungsvariable
`NUXT_PUBLIC_API_BASE` gesetzt sein, sonst schlaegt der Build fehl.
::

Normale Absaetze funktionieren weiterhin wie gewohnt, aber
Komponenten mit Props koennen direkt eingebettet werden:

::code-preview{filename="app.vue" language="vue"}
#default
Hier steht der eigentliche Vorschau-Inhalt als Slot.
::

6. Automatisches Routing mit Catch All Seiten

Nuxt Content entfaltet seine volle Stärke in Kombination mit einer einzigen Catch All Route, meist als [...slug].vue in pages/ angelegt. Diese eine Vue Komponente bedient jede Markdown Datei im Content Verzeichnis, indem sie den aktuellen Pfad aus der URL liest, den passenden Content Eintrag per Query Builder lädt und über die ContentRenderer Komponente ausgibt. Damit entfällt für jede neue Markdown Datei die Notwendigkeit, eine eigene Vue Seite anzulegen.

Dieses Muster skaliert hervorragend: Ob zehn oder fünfhundert Markdown Dateien im Projekt liegen, die Routing Logik bleibt identisch, weil Nuxt Content die Zuordnung zwischen URL und Datei automatisch aus der Verzeichnisstruktur ableitet. Für Sonderfälle, etwa eine Startseite mit komplett eigenem Layout, kann parallel eine dedizierte Seite existieren, während alle übrigen Inhalte über die Catch All Route laufen.

// pages/[...slug].vue
<script setup>
const route = useRoute()
const { data: page } = await useAsyncData(route.path, () =>
  queryCollection('content').path(route.path).first()
)

if (!page.value) {
  throw createError({ statusCode: 404, statusMessage: 'Seite nicht gefunden' })
}
</script>

<template>
  <article>
    <h1>{{ page.title }}</h1>
    <ContentRenderer :value="page" />
  </article>
</template>

7. Volltextsuche und Navigation aufbauen

Für die Volltextsuche bringt Nuxt Content das Composable queryCollectionSearchSections mit, das den gerenderten Text aller Seiten in durchsuchbare Abschnitte zerlegt, jeweils mit Überschrift, Ankerpunkt und Textauszug. Kombiniert mit einer clientseitigen Suchbibliothek wie Fuse.js oder Minisearch entsteht so eine vollständige Suchfunktion, ohne dass ein externer Suchindex wie Algolia oder Elasticsearch betrieben werden muss.

Für die Navigation liefert das Composable queryCollectionNavigation automatisch einen verschachtelten Baum aus der Verzeichnisstruktur inklusive der Titel aus dem Frontmatter. Diese Navigation lässt sich direkt in eine Sidebar Komponente rendern und bleibt automatisch synchron mit den tatsächlich vorhandenen Markdown Dateien. Fehlt eine Seite in der Navigation, liegt es fast immer daran, dass die Datei nicht dem erwarteten Namensschema entspricht oder ein draft: true Feld sie versteckt.

8. Typische Fallstricke im Praxiseinsatz

Der häufigste Fehler beim Einstieg in Nuxt Content ist das Vergessen des Entwicklungsservers Neustarts nach strukturellen Änderungen am Content Verzeichnis. Anders als bei reinen Vue Dateien wird das Content Schema nur beim Serverstart neu aufgebaut, weshalb neu angelegte Collections manchmal erst nach einem Neustart sichtbar werden. Ein zweiter Fallstrick betrifft die Groß und Kleinschreibung von Dateinamen: Auf Linux Produktionsservern führt Inkonsistenz zwischen lokalem macOS Dateisystem und Server zu fehlenden Seiten, die lokal einwandfrei funktionierten.

Ein dritter, subtiler Fehler ist das Vermischen von rohem HTML und MDC Syntax in derselben Datei. Rohes HTML wird von Nuxt Content standardmäßig escaped, was bei Redakteuren, die aus einem klassischen CMS kommen, zu Verwirrung führt. Die korrekte Lösung ist immer, gewünschte interaktive Elemente als registrierte MDC Komponente bereitzustellen, statt HTML direkt in Markdown einzubetten. Wer zusätzlich Bilder referenziert, sollte relative Pfade konsequent aus dem public/ Verzeichnis auflösen, da absolute Dateisystempfade beim Production Build nicht funktionieren.

9. Nuxt Content im Vergleich zu Alternativen

Die Entscheidung für Nuxt Content hängt stark vom Projektkontext ab. Gegenüber einem klassischen Headless CMS wie Contentful oder Strapi entfällt zusätzliche Infrastruktur, dafür ist die Bearbeitung durch nicht technische Redakteure ohne Adminoberfläche erschwert. Die folgende Tabelle stellt die wichtigsten Optionen für inhaltsgetriebene Nuxt Projekte gegenüber.

In der Praxis zeigt sich, dass Nuxt Content genau die Lücke zwischen reinem statischen Markdown und einem vollen Headless CMS schließt. Für Projekte, in denen Entwickler die Inhalte pflegen oder Redakteure mit Git vertraut sind, ist der Aufwand für ein separates CMS meist nicht gerechtfertigt. Nuxt Content bringt Versionierung, Review Prozesse per Pull Request und volle Kontrolle über das Rendering direkt mit, ohne zusätzliche vertragliche Abhängigkeit von einem SaaS Anbieter.

10. Zusammenfassung

Nuxt Content löst das wiederkehrende Problem, Inhalte ohne externe Datenbank oder CMS zu verwalten und trotzdem eine durchsuchbare, filterbare Datenschicht zu haben. Markdown Dateien mit Frontmatter werden zur Build Zeit in eine SQLite Datenbank überführt, der Query Builder erlaubt komplexe Abfragen nach Feldern, Tags und Volltext. Die MDC Syntax erlaubt echte Vue Komponenten direkt im Markdown Text, ohne dass Redakteure HTML schreiben müssen.

Eine einzige Catch All Route bedient beliebig viele Markdown Dateien, und automatisch generierte Navigationsbäume bleiben ohne manuelle Pflege synchron mit der Verzeichnisstruktur. Für Dokumentationsseiten, technische Blogs und Marketing Landingpages ist Nuxt Content damit häufig die pragmatischere Alternative zu einem vollen Headless CMS, insbesondere wenn Entwickler selbst die Inhalte pflegen oder Git basierte Review Prozesse gewünscht sind.

11. FAQ: Nuxt Content und Markdown basierte Seiten