Contribuindo com a documentação (multi-repo)

Este portal (Docusaurus) vive no repositório superapp e agrega a documentação de vários serviços da Meresolve. Cada serviço mantém sua própria documentação no próprio repositório; o portal a coleta no build via git submodules.

O contrato: como cada repo publica sua doc

Cada repositório-fonte deve expor uma pasta na raiz chamada docs-portal/ contendo apenas conteúdo Markdown/MDX:

<repo>/
└── docs-portal/
    ├── index.md            # página inicial da seção do serviço
    ├── <outros>.md/.mdx     # demais páginas
    ├── img/                 # imagens/assets referenciados
    └── openapi.yaml         # (opcional) spec da API do serviço

Regras do contrato:

• Só conteúdo. Nada de docusaurus.config.ts, package.json, node_modules. O único Docusaurus é o do portal (superapp). Os outros repos guardam apenas os .md/.mdx e assets.
• Frontmatter em cada página:

  ---
  sidebar_position: 1
  title: Título da página
  ---

• Markdown/MDX, não Markdoc. Nada de tags {% ... %}.
• Links relativos entre páginas do mesmo serviço (./outra-pagina.md).
• Um index.md na raiz da pasta serve de landing da seção do serviço.
• Diagramas em Mermaid, nunca em ASCII. Fluxos, arquiteturas e sequências devem usar blocos ```mermaid, que o portal renderiza como diagrama de verdade (pesquisável, responsivo e legível no claro/escuro). Não use "desenhos" em ASCII (caixas com │, ▼, setas de texto): ficam quebrados em telas pequenas e não são acessíveis. Ao editar uma página antiga que ainda tenha um diagrama em ASCII, aproveite e converta para Mermaid.

Exemplo: fluxo em Mermaid

```mermaid
flowchart TD
    A["Tela (React)"] --> B["Server Action"]
    B --> C["Service"]
    C --> D[("Banco (RLS)")]
```

O Mermaid já vem habilitado no portal. Referência da sintaxe: mermaid.js.org.

Serviços agregados

Os repositórios já registrados como submodule em docs-portal/external/:

Serviço	Repositório	Pasta de doc	Status
API Placa	MeResolve/api-placa	docs-portal/	a criar
James	MeResolve/james	docs-portal/	a criar
Airflow DAGs	MeResolve/airflow-dags (ETLs do DW)	docs-portal/	a criar

Enquanto a pasta docs-portal/ não existir no repo, o serviço não aparece no portal (a seção fica desligada para não quebrar o build).

Como plugar um serviço no portal

Quando um repo-fonte já tiver sua pasta docs-portal/ com conteúdo:

1. Atualizar o submodule para o commit que contém a pasta:

   git submodule update --remote docs-portal/external/<repo>

2. Descomentar a instância do plugin em docs-portal/docusaurus.config.ts (bloco plugins), ajustando id, path e routeBasePath.

3. Descomentar a sidebar correspondente em docs-portal/sidebars.ts.

4. Adicionar o item na navbar (themeConfig.navbar.items) apontando para a nova routeBasePath.

5. Validar o build:

   cd docs-portal
   pnpm build

Como o build resolve os submodules

No deploy (Cloudflare Pages), o build precisa inicializar os submodules antes de rodar o Docusaurus:

git submodule update --init --recursive
cd docs-portal
pnpm install
pnpm build

No Cloudflare Pages, habilitar a opção de checkout de submodules (ou usar um build command que rode git submodule update --init antes do pnpm build).