Content-Modell

Dateien

Ein Dokument entspricht einer .mdx- oder .md-Datei im Ordner des jeweiligen Typs:

content/
  blog/
    hello-world.mdx        → slug "hello-world"
    _redirects.json        → redirect rules for this type (optional)
  authors/
    jane.mdx               → slug "jane"

• Der Dateiname ist der englische Slug. Slugs werden komplett kleingeschrieben und nutzen Bindestriche (Kebab-Case).
• Auf der Festplatte existieren ausschließlich englische Dateien. Die lokalisierten Versionen werden in der SQLite-Datenbank gespeichert.
• Dateien, deren Name mit einem _ oder einem Großbuchstaben beginnt (wie PUBLISHING.md), werden ignoriert. So können Sie Notizen direkt neben Ihren Inhalten ablegen.

Frontmatter

Das Frontmatter nutzt YAML und wird anhand des Zod-Schemas des jeweiligen Typs validiert:

---
title: "Hello, world"
description: "A long enough description for the schema."
author: jane
publishedAt: "2026-01-15"
updatedAt: "2026-02-01"
---

Body is MDX.

Die Schema-Validierung richtet sich nach Ihrem Zod-Schema. Bei einem einfachen z.object werden unbekannte Schlüssel stillschweigend ignoriert. Verwenden Sie .strict(), wenn Tippfehler in Feldnamen sofort zu einem Validierungsfehler führen sollen.

Integrierte Frontmatter-Felder

Diese Felder stehen für jeden Inhaltstyp zur Verfügung, ohne dass Sie diese im Schema definieren müssen. Sie werden aus dem Frontmatter extrahiert, bevor das Schema greift. Eine Deklaration in Ihrem Zod-Schema hat daher keine Auswirkungen:

Feld	Typ	Beschreibung
publishedAt	ISO-Datum	Veröffentlichungsdatum.
updatedAt	ISO-Datum	Letztes größeres Update. Standardmäßig auf publishedAt gesetzt. Steuert lastModified in der Sitemap.
noindex	boolean	Wird aus der Sitemap ausgeschlossen. Sie können dies als Robots-Meta-Tag auf Ihren Seiten ausgeben.
canonicalPath	string	Manuelles Überschreiben des kanonischen URL-Pfads.

Lokalisierte Dokumente erben publishedAt, updatedAt, noindex und canonicalPath vom englischen Original. Übersetzer können diese Werte nicht anpassen.

Jedes geladene Dokument enthält zudem die Felder slug, enSlug (der Slug des englischen Originals, der bei englischen Dokumenten mit dem slug identisch ist), locale, frontmatter und content.

Typen ohne Body

Reine Referenz-Kollektionen (wie ein model oder eine category, deren Schema rein strukturell aufgebaut ist) kommen oft ganz ohne MDX-Body aus. Deklarieren Sie body: false im Typ, um dies explizit festzulegen:

defineContentType({
  id: "model",
  contentDir: "models",
  schema: modelSchema,
  body: false, // entries are frontmatter-only
});

Der Standardwert ist body: true, was die vollständige Abwärtskompatibilität sichert. Bei einem Typ mit body: false führt jeglicher Textinhalt im Body zu einem Validierungsfehler. Der Loader überspringt das MDX-Parsing und statische Exporte geben keinen Body aus. Ein Typ ohne Body, der keine übersetzbaren Felder besitzt, wird aus allen Übersetzungs-Workflows ausgeschlossen. Enthält ein solcher Typ jedoch ein übersetzbares Feld, bleibt er in der Aufgabenliste mit einem reinen Frontmatter-Payload erhalten. Weitere Informationen zur Übersetzbarkeit finden Sie unter Übersetzung.

Mehr als nur Frontmatter

MDX-Bodies bieten weit mehr als einfachen Text:

• Inline-Token betten Links, Asset-URLs und unübersetzbare Literale direkt im Body ein. Diese werden beim Lesen pro Gebietsschema aufgelöst.
• Assets, die mit field.asset() deklariert wurden, werden auf der Festplatte validiert und beim Laden in öffentliche URLs umgewandelt.

Weiterleitungen: _redirects.json

Sie können jedem Ordner eines Inhaltstyps eine optionale Datei namens _redirects.json hinzufügen. Darin definieren Sie Slug-Migrationen und entfernte Dokumente. Diese Weiterleitungen bleiben erhalten, auch wenn Sie die ursprüngliche MDX-Datei löschen. Übersetzte Quell-Slugs werden automatisch aus SQLite aufgelöst.

{
  "redirects": [
    { "from": "hello-world", "toSlug": "hello-scribe" },
    { "from": ["old-a", "old-b"], "toSlug": "hello-scribe" },
    { "from": "moved-post", "toType": "glossary", "toSlug": "virtual-try-on" },
    { "from": "retired-page", "toUrl": "/pricing" },
    { "from": "retired-ext", "toUrl": "https://example.com/app" }
  ]
}

Es gibt drei Arten von Weiterleitungen (mit genau einem Ziel pro Eintrag):

Art	Felder	Beschreibung
Gleicher Typ	toSlug	Ziel ist ein englischer Slug im selben Inhaltstyp. Die URL wird aus dem path dieses Typs gebildet und pro Gebietsschema lokalisiert.
Typübergreifend	toType + toSlug	Ziel ist ein englischer Slug in einem anderen aufrufbaren Inhaltstyp (dieser muss einen path besitzen).
Beliebig	toUrl	Ein relativer Pfad auf derselben Website oder eine absolute externe URL. Dieser Wert ist für jedes Gebietsschema identisch.

• from: Gilt nur für englische Slugs. Übersetzte Quell-Slugs werden aus SQLite aufgelöst.
• Optional permanent (Standard ist true).

So entfernen oder benennen Sie ein Dokument um: Fügen Sie einen Eintrag in die _redirects.json ein und löschen (oder benennen) Sie die MDX-Quelldatei. Führen Sie danach scribe validate aus und starten Sie den Build-Prozess neu. Die Weiterleitungsregeln werden durch buildAllContentRedirects() für Ihren Proxy oder Ihre Framework-Konfiguration bereitgestellt.

Validierung

scribe validate

Für jede englische Datei wird Folgendes geprüft: Schema-Parsing, das Format der integrierten Felder, Ihr crossValidate-Hook und die MDX-Kompilierung des Bodys. Ein Body, der sich nicht als MDX parsen lässt, stellt sowohl für englische Originale als auch für gespeicherte Übersetzungen einen Fehler dar, der den Build blockiert.

Projektweit werden zudem folgende Aspekte kontrolliert: Integrität der Relationen (fehlende Pflichtrelationen erzeugen Fehler, fehlende optionale Relationen erzeugen Warnungen), Regeln der _redirects.json (gültige Ziele, keine doppelten Quellen, keine Weiterleitungsketten), Suffix-Regeln für lokalisierte Slugs, deklarierte Asset-Felder (Vorhandensein der Datei, formats, maxKB), Inline-Body-Token (fehlerhafte Spans, fehlende Relationen, :href zu nicht aufrufbaren Typen, fehlende vars-Schlüssel, fehlende Asset-Dateien), body: false-Typen mit unerlaubtem Body-Inhalt, fehlende Bild-Assets (sofern das Asset-Verzeichnis festgelegt ist) sowie die Existenz der Übersetzungsdatenbank.

Sobald ein Fehler gefunden wird, ist der Exit-Code ungleich null. Führen Sie diesen Befehl daher vor Ihrem Build aus:

{
  "scripts": {
    "build": "scribe validate && <your framework build>"
  }
}