Modello di contenuto

File

Ogni documento corrisponde a un singolo file .mdx (o .md) all'interno della cartella del tipo di contenuto:

content/
  blog/
    hello-world.mdx        → slug "hello-world"
    _redirects.json        → regole di reindirizzamento per questo tipo (facoltativo)
  authors/
    jane.mdx               → slug "jane"

• Il nome del file funge da slug in inglese. Gli slug utilizzano il formato kebab-case in minuscolo.
• Nel file system sono presenti solo i file in inglese; le versioni tradotte risiedono nell'archivio SQLite.
• I file che iniziano con _ o con una lettera maiuscola (come PUBLISHING.md) vengono ignorati, consentendoti di conservare appunti o documentazione interna accanto ai contenuti.

Frontmatter

Il frontmatter utilizza YAML e viene validato secondo lo schema Zod associato al tipo di contenuto:

---
title: "Hello, world"
description: "Una descrizione sufficientemente lunga per lo schema."
author: jane
publishedAt: "2026-01-15"
updatedAt: "2026-02-01"
---

Il corpo del documento è in MDX.

La validazione avviene tramite il tuo schema Zod: con un normale z.object, i campi sconosciuti vengono semplicemente scartati senza generare errori; usa .strict() se preferisci che eventuali errori di battitura nei nomi dei campi blocchino la validazione.

Campi frontmatter predefiniti

I seguenti campi sono disponibili in tutti i tipi di contenuto senza doverli dichiarare nello schema. Vengono estratti dal frontmatter prima dell'esecuzione dello schema, pertanto aggiungerli al tuo schema Zod non sortirà alcun effetto:

Campo	Tipo	Descrizione
publishedAt	data ISO	Data di pubblicazione.
updatedAt	data ISO	Data dell'ultimo aggiornamento rilevante. Se assente, utilizza il valore di publishedAt. Utile per il campo lastModified della sitemap.
noindex	boolean	Esclude il documento dalla sitemap. Puoi usare questo valore per generare un meta tag robots nelle tue pagine.
canonicalPath	string	Consente di sovrascrivere manualmente il percorso URL canonico.

I documenti tradotti ereditano publishedAt, updatedAt, noindex e canonicalPath dal documento originale in inglese e i traduttori non possono modificarli.

Ogni documento caricato include inoltre le proprietà slug, enSlug (lo slug del documento originale, uguale a slug per i documenti in inglese), locale, frontmatter e content.

Tipi di contenuto senza corpo (Bodyless)

Le raccolte destinate esclusivamente a fungere da riferimenti (come un tipo model o category con uno schema prettamente strutturale) spesso non includono alcun corpo MDX. Puoi indicarlo chiaramente aggiungendo body: false alla definizione del tipo:

defineContentType({
  id: "model",
  contentDir: "models",
  schema: modelSchema,
  body: false, // le voci contengono solo frontmatter
});

Il valore predefinito è body: true, garantendo piena retrocompatibilità. Se un tipo è configurato con body: false, la presenza di testo nel corpo (esclusi gli spazi bianchi) genera un errore di validazione, il parser ignora la lettura dell'MDX e le esportazioni statiche non includono il corpo. Inoltre, un tipo senza corpo e con zero campi traducibili viene escluso completamente dal flusso di traduzione (evitando avvisi inutili per documenti mancanti o obsoleti); se invece contiene almeno un campo traducibile, rimarrà nell'elenco delle attività da completare, inviando ai traduttori esclusivamente i dati del frontmatter. Consulta la sezione traduzione per i dettagli sulle regole di traducibilità.

Oltre il frontmatter

I corpi in formato MDX offrono funzionalità avanzate rispetto al semplice testo:

• I token inline permettono di inserire collegamenti, URL per gli asset e stringhe non traducibili direttamente all'interno del corpo. Tali elementi vengono elaborati e localizzati durante la fase di lettura.
• Gli asset definiti tramite field.asset() vengono verificati all'interno del file system e convertiti in URL pubblici al momento del caricamento.

Reindirizzamenti: _redirects.json

All'interno di ogni cartella associata a un tipo di contenuto, è possibile includere un file facoltativo _redirects.json per gestire modifiche agli slug e documenti non più attivi. I reindirizzamenti restano operativi anche dopo la rimozione del file MDX d'origine. Gli slug tradotti di origine vengono generati automaticamente a partire dal database SQLite.

{
  "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" }
  ]
}

Esistono tre tipologie di reindirizzamento (con esattamente una destinazione per ogni voce):

Tipologia	Campi	Descrizione
Stesso tipo	toSlug	Punta allo slug in inglese (EN) all'interno del medesimo tipo di contenuto. L'URL viene generato a partire dal path del tipo di contenuto e localizzato in base alla lingua.
Tra tipi diversi	toType + toSlug	Punta allo slug in inglese in un altro tipo di contenuto dotato di percorso (deve avere la proprietà path).
Qualsiasi destinazione	toUrl	Percorso all'interno dello stesso sito relativo alla radice o un URL esterno assoluto, identico per tutte le lingue.

• from: accetta solo slug in inglese. Gli slug tradotti d'origine vengono determinati tramite SQLite.
• Proprietà facoltativa permanent (predefinita a true).

Per dismettere o rinominare un documento, aggiungi un record nel file _redirects.json, rimuovi (o cambia il nome al) file MDX d'origine, dopodiché esegui scribe validate e compila nuovamente il progetto. Le regole di reindirizzamento vengono prodotte dalla funzione buildAllContentRedirects() per essere utilizzate nella configurazione del tuo proxy o framework.

Validazione

scribe validate

Per ogni file in inglese esegue i seguenti controlli: parsing in base allo schema, formato corretto per i campi integrati, validazione tramite il tuo hook crossValidate e la compilazione MDX del corpo. Un corpo che non è in formato MDX valido causerà un errore che bloccherà la compilazione, sia per i file originali in inglese sia per le traduzioni salvate.

A livello di intero progetto verifica inoltre: l'integrità delle relazioni (una relazione obbligatoria mancante genera un errore, una facoltativa genera un avviso), la correttezza delle regole in _redirects.json (destinazioni valide, assenza di sorgenti duplicate o di catene di reindirizzamenti), le norme relative ai suffissi degli slug localizzati, i campi per gli asset definiti nello schema (presenza del file, corrispondenza dei formats e rispetto dei maxKB), i token inseriti nel corpo (span malformati, riferimenti mancanti, :href che puntano a tipi senza percorso web, mancanza della proprietà vars o file degli asset inesistenti), i tipi definiti con body: false che contengono del testo, l'assenza di immagini qualora sia impostata una cartella dedicata agli asset e la presenza del database per le traduzioni.

Se viene rilevato un problema qualsiasi, il codice di uscita non sarà zero; assicurati di eseguire il comando prima della fase di compilazione (build):

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