Como funcionam os docs

Este site é Docusaurus 3 (preset classic + faster), em Documents/H1/docs, em pt-BR. O conteúdo é Markdown — sem app/backend.

Arquitetura: 1 aba = 1 instância de docs

Cada aba do topo é uma instância separada de @docusaurus/plugin-content-docs, com seu próprio routeBasePath, pasta de conteúdo e arquivo de sidebar:

Aba	Instância (id)	Pasta	Rota	Sidebar
Impressão	default (preset)	docs-printing/	/printing	sidebarsPrinting.ts
Gestão de Ativos	asset-management	docs-asset-management/	/asset-management	sidebarsAssetManagement.ts
Middleware	middleware	docs-middleware/	/middleware	sidebarsMiddleware.ts
Plataforma	platform	docs-platform/	/platform	sidebarsPlatform.ts
Páginas	pages	docs-pages/	/paginas	sidebarsPages.ts
Developer	developer	docs-developer/	/developer	sidebarsDeveloper.ts

Os itens da navbar são links simples {to, label} (não docSidebar). A busca (@easyops-cn/docusaurus-search-local) indexa todas as instâncias listadas em docsRouteBasePath — ao criar uma aba nova, adicione a rota lá também.

Convenções

• Arquivos .md, em pt-BR (termos/commands em inglês ok).
• Frontmatter: sidebar_position, title (+ description/keywords quando útil). A landing da instância usa slug: /.
• Categorias = subpasta + _category_.json ({"label": "...", "position": N}).
• Sidebars quase todas manuais (lista explícita de ids); a chave de export é main.
• Admonitions: :::tip, :::note, :::info, :::warning Título … :::.

Adicionar uma página

1. Crie docs-<instância>/minha-pagina.md com frontmatter (title, sidebar_position).
2. Adicione o id (minha-pagina, sem extensão) no sidebars<Instância>.ts.

Adicionar uma aba (nova instância) — como esta "Developer" foi feita

1. docusaurus.config.ts → adicione um item em plugins:

   ['@docusaurus/plugin-content-docs',
     { id: 'developer', path: 'docs-developer', routeBasePath: 'developer',
       sidebarPath: './sidebarsDeveloper.ts' }],

2. Adicione a rota em themeConfig.navbar.items: {to: '/developer', label: 'Developer', position: 'right'}.
3. Adicione '/developer' no docsRouteBasePath da busca.
4. Crie sidebarsDeveloper.ts (export main) e a pasta docs-developer/ com um intro.md (slug: /).

Mudanças no docusaurus.config.ts não têm hot-reload — reinicie o npm run start.

Rodar e buildar

cd docs
npm run start       # dev em :3000
npm run build       # build de produção (estático)
npm run typecheck   # tsc
npm run serve       # serve o build

API docs (OpenAPI) — instalado mas desativado

Existe uma pasta órfã docs-api/ + sidebarsApi.ts e as deps docusaurus-plugin-openapi-docs / docusaurus-theme-openapi-docs no package.json, mas não há instância registrada no docusaurus.config.ts — o tooling de OpenAPI está presente porém desligado. O HSBR-Gestao-Ativos-Back gera um docs/openapi.generated.json (via npm run docs:generate); para publicar a referência da API aqui, bastaria registrar uma instância OpenAPI apontando para esse arquivo (mesma receita de "adicionar uma aba" acima).