Runbook — Build local das docs

Pré-requisitos

• Node.js ≥ 18 (node --version)
• Repositório clonado; comandos executados dentro de site/

1. Instalar dependências (primeira vez)

cd site
npm install

2. Desenvolvimento (hot reload)

npm run start

Abre http://localhost:3000. Alterações em docs/ recarregam automaticamente. Este modo não valida tudo — links quebrados só aparecem no build.

3. Validação completa

npm run docs:check

Executa, nesta ordem:

1. Validação de biblioteca (scripts/docs-check.js): frontmatter obrigatório, owner, status válido, APPROVED sem version, nomes proibidos (FINAL/latest/…), slugs duplicados.
2. Build de produção (docusaurus build): falha em link interno quebrado (onBrokenLinks: throw).

Resultado esperado: DOCS CHECK: PASS e build concluído sem erros. Qualquer FAIL bloqueia publicação.

4. Inspecionar o build de produção

npm run serve

Serve a pasta build/ como será publicada.

Problemas comuns

Sintoma	Causa provável	Ação
Build falha com "broken link"	Link relativo errado após renomear arquivo	Corrigir o link; nunca ignorar
Erro de compilação MDX em um .md	Sintaxe {/< interpretada como JSX	Escapar o trecho com crases (código)
docs-check acusa frontmatter	Campo obrigatório ausente	Completar conforme Documentation Standard