Guia — Site de documentação e ferramentas (EBDbe)

Este guia descreve como o site de documentação do projeto é gerado, que ferramentas usar, comandos oficiais, deploy e boas práticas para quem edita conteúdo.

Índice (tipos de documento): ORGANIZACAO-DOCUMENTOS.md.

README da pasta docs/ (raiz do repositório, fora do Starlight): no repositório em docs/README.md.

1. Visão geral

Conceito	Descrição
Conteúdo	Markdown (`.md`), MDX (`.mdx`) em `docs/src/content/docs/` (árvore `architecture/`, `prd/`, `vision/`, etc.).
Site estático	Astro 6 + Starlight; saída em `docs/dist/`, consumida pelo Firebase Hosting (+ função `docsGateway` para rewrites).
Scripts na raiz	`scripts/start-docs.ps1` (dev) e `scripts/build-docs.ps1` (build + opcional Storage + deploy).

2. Requisitos de ambiente

Ferramenta	Notas
Node.js	≥ 22.12.0 (linha 22.x LTS; evitar versões ímpares não suportadas pelo Astro).
npm	Em `docs/` para dependências e scripts.
PowerShell	Recomendado PowerShell 7+ para `scripts/*.ps1`.
Firebase CLI	Para `firebase deploy` da documentação.
Google Cloud SDK (`gcloud`)	Para `gcloud storage rsync` no fluxo de `build-docs.ps1`.

Pin de versão: .nvmrc na raiz do repositório com 22.

Configuração do site:

docs/astro.config.mjs — integrações Astro/React/Starlight, título, sidebar (autogenerate), CSS custom.
docs/src/content.config.ts — coleção de conteúdo Starlight.
docs/public/ — ficheiros estáticos servidos na raiz do site (/img/..., /data/git-history.json).
docs/src/components/ — componentes React (ex.: GitHistoryPage.tsx) usados em MDX com client:load.
docs/src/styles/custom.css — tema (accent) EBDbe.

3. Comandos — desenvolvimento local

3.1 Script recomendado (raiz do repositório)

.\scripts\start-docs.ps1

Parâmetro	Efeito
`-Port 3001`	Porta alternativa (padrão 3000).
`-SkipInstall`	Não corre `npm install` se já existir `node_modules`.

Corre npx astro dev dentro de docs/ (por defeito http://localhost:3000).

3.2 Comandos manuais (`docs/`)

Atenção: estes comandos têm de ser executados com a pasta atual docs/ (onde está o package.json). Se correres npm run build na raiz do repositório (ebdbe/), aparece ENOENT: no such file or directory, open '...\package.json'.

cd docs
npm install
npm run dev      # ou npm run start — servidor de desenvolvimento
npm run build    # saída em dist/
npm run preview  # pré-visualizar o build estático (pesquisa Pagefind)

Na raiz do clone podes usar .\scripts\preview-docs.ps1 (faz build + preview em docs/).

4. Build e publicação

4.1 `build-docs.ps1`

Exporta dados para Histórico Git (scripts/export-git-history.ps1 → docs/public/data/git-history.json).
Em docs/: npm install + npm run build (Astro).
Verifica docs/dist/.
Sem -BuildOnly: gcloud storage rsync + firebase deploy --only hosting:<target>.

Parâmetro	Valores
`-Target`	`docs-prod` (padrão), `docs-dev`
`-BuildOnly`	Só gera `docs/dist/`, sem upload/deploy

4.2 Firebase Hosting

Em firebase.json, targets docs-dev e docs-prod usam public": "docs/dist" e rewrites para docsGateway.

5. Estrutura de pastas (`docs/`)

Área	Conteúdo
`docs/src/content/docs/`	Toda a documentação publicada no site (PRD, ADR, TDD, UI, …).
`docs/public/`	Assets e JSON gerado (`data/git-history.json`).
`docs/dist/`	Gerado pelo `astro build` — não editar.
`docs/README.md`	Notas para quem abre o repositório (não é rota Starlight).

6. Front matter (Starlight)

Cada página deve ter no topo um bloco YAML com pelo menos title (obrigatório no schema Starlight).

Exemplo:

---
title: 'Título da página'
description: 'Opcional — subtítulo / SEO'
sidebar:
  order: 10
---

Para normalizar ficheiros legados (Docusaurus) em massa existe o script:

node scripts/normalize-starlight-docs-frontmatter.mjs

(Corrige blocos --- partidos e define title a partir do primeiro # quando falta.)

7. Histórico Git

A página Histórico Git (git-history) carrega /data/git-history.json, gerado pelo export antes do build. Sem esse ficheiro, a UI mostra erro ao carregar.

8. Links

URLs no site seguem a pasta em src/content/docs/ (ex.: /architecture/adrs/adr-0001-.../).
Preferir links relativos entre .md na mesma árvore.

9. Atualizar dependências

cd docs
npm outdated
npm run build
npx @astrojs/upgrade   # opcional — upgrades oficiais Astro/Starlight

10. Referências rápidas

Ficheiro / pasta	Assunto
`docs/README.md`	Resumo e atalhos
`scripts/start-docs.ps1`	Dev
`scripts/preview-docs.ps1`	Build + `preview` em `docs/` (testar pesquisa; porta 4321)
`scripts/build-docs.ps1`	Build + deploy
`scripts/normalize-starlight-docs-frontmatter.mjs`	Front matter em lote
`firebase.json`	Hosting `docs-dev` / `docs-prod`
Starlight / Astro	Documentação oficial

Stack atual: Astro 6 + Starlight; saída docs/dist/.