Modelo de conteúdo

Arquivos

Cada documento é representado por um arquivo .mdx (ou .md) na pasta do tipo de conteúdo:

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

• O nome do arquivo é o slug em inglês. Os slugs usam o formato kebab-case em letras minúsculas.
• Apenas os arquivos em inglês existem no disco. As versões localizadas ficam armazenadas no banco SQLite.
• Arquivos com nomes iniciados por _ ou por uma letra maiúscula (como PUBLISHING.md) são ignorados. Isso permite que você guarde anotações junto do seu conteúdo.

Frontmatter

O frontmatter usa o formato YAML e é validado pelo schema Zod do tipo de conteúdo:

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

Body is MDX.

A validação segue o seu schema Zod. Se você usar um z.object simples, as chaves desconhecidas serão removidas silenciosamente. Use .strict() caso queira que erros de digitação nos nomes dos campos gerem falhas de validação.

Campos nativos do frontmatter

Estes campos estão disponíveis em todos os tipos de conteúdo sem precisar declará-los no schema. Como eles são extraídos do frontmatter antes da execução do seu schema, declará-los no Zod não surtirá nenhum efeito:

Campo	Tipo	Descrição
publishedAt	ISO date	Data de publicação.
updatedAt	ISO date	Última atualização significativa. O padrão é publishedAt. Controla o lastModified do sitemap.
noindex	boolean	Remove a página do sitemap (você pode expor esse valor como uma meta tag robots nas suas páginas).
canonicalPath	string	Substitui manualmente o caminho da URL canônica.

Os documentos localizados herdam os campos publishedAt, updatedAt, noindex e canonicalPath da versão original em inglês, não sendo possível alterá-los durante a tradução.

Todo documento carregado também inclui slug, enSlug (o slug original em inglês, que é igual ao slug para documentos em inglês), locale, frontmatter e content.

Tipos sem corpo (bodyless)

Coleções que servem apenas como referência (como um tipo model ou category cujo schema é totalmente estrutural) costumam não ter nenhum corpo em MDX. Para deixar isso explícito, declare body: false no tipo:

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

Como o padrão é body: true, essa configuração é totalmente compatível com versões anteriores. Em um tipo body: false, qualquer conteúdo no corpo que não seja espaço em branco gera um erro de validação. Além disso, o loader pula a análise do MDX e as exportações estáticas não emitem corpo algum. Um tipo sem corpo que também tem zero campos traduzíveis é removido de todos os fluxos de tradução (evitando alertas falsos de conteúdo ausente ou desatualizado). Já um tipo sem corpo que ainda possui algum campo traduzível permanece nas tarefas pendentes, mas apenas com os dados do frontmatter. Consulte as regras de tradução em translation.

Além do frontmatter

Os corpos em MDX podem fazer muito mais do que apenas exibir texto simples:

• Os Inline tokens incorporam links, URLs de arquivos e valores literais não traduzíveis diretamente no corpo. Tudo é resolvido por idioma no momento da leitura.
• Os Assets declarados com field.asset() são validados no disco e convertidos em URLs públicas durante o carregamento.

Redirecionamentos: _redirects.json

Você pode adicionar um arquivo opcional _redirects.json a cada pasta de tipo de conteúdo para gerenciar migrações de slugs e documentos removidos. Os redirecionamentos continuam funcionando mesmo após a exclusão do MDX original. Além disso, os slugs traduzidos de origem são expandidos automaticamente a partir do banco 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" }
  ]
}

Existem três tipos de redirecionamentos (com exatamente um destino por entrada):

Tipo	Campos	Descrição
Mesmo tipo	toSlug	O slug de destino em inglês dentro do mesmo tipo de conteúdo. A URL é construída a partir do path desse tipo e localizada para cada idioma.
Tipo cruzado	toType + toSlug	O slug de destino em inglês em outro tipo de conteúdo com rota (precisa ter um path).
Qualquer lugar	toUrl	Um caminho relativo à raiz no mesmo site ou uma URL externa absoluta, idêntico para todos os idiomas.

• from: Apenas slug(s) em inglês. Os slugs de origem já traduzidos são resolvidos pelo SQLite.
• Campo opcional permanent (o padrão é true).

Para remover ou renomear um documento, siga este processo simples: adicione uma entrada no arquivo _redirects.json, exclua (ou renomeie) o MDX de origem, rode o comando scribe validate e gere uma nova build. As regras de redirecionamento são emitidas por buildAllContentRedirects() para uso no seu proxy ou nas configurações do framework.

Validação

scribe validate

Esse comando verifica cada arquivo em inglês, analisando o schema, os formatos dos campos nativos, o seu hook crossValidate e a compilação MDX do corpo. Se o corpo não puder ser processado como MDX, um erro bloqueará o build. Isso vale tanto para os arquivos originais em inglês quanto para as traduções guardadas no banco.

No escopo do projeto, a ferramenta também realiza diversas validações adicionais. O comando checa a integridade das relações (relações obrigatórias quebradas geram erro, enquanto as opcionais geram aviso), verifica as regras do _redirects.json (destinos válidos, ausência de origens duplicadas e inexistência de cadeias de redirecionamento) e analisa as regras de sufixo para slugs localizados. Também audita os arquivos de assets declarados (verificando a existência do arquivo, formats e maxKB) e os inline body tokens (procurando tags malformadas, links quebrados, :href apontando para tipos sem rota, chaves vars ausentes ou arquivos de assets inexistentes). Por fim, o script confere se os tipos marcados como body: false contêm texto indevido, se faltam imagens quando o diretório de assets está configurado e se o armazenamento de tradução existe.

O código de saída será diferente de zero sempre que algum erro for encontrado. Recomendamos executá-lo antes do seu build:

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