Arquitetura Técnica do Docs

Arquitetura Técnica do Docs

Decisão

O Docs usa Astro + Starlight para renderizar documentação estática premium e Netlify Free para publicação pública em domínio próprio.

MDs canônicos no repo
        ↓
scripts/sync-content.mjs
        ↓
05-docs-site/src/content/docs/
        ↓
Astro Starlight
        ↓
Build validado
        ↓
Netlify / docs.techhuman.com.br

---

Princípios

Princípio	Decisão
Fonte única	Os MDs originais continuam fora do site, no repositório
UX premium	Starlight entrega busca, sidebar, TOC, responsividade e acessibilidade
Sem duplicação manual	O script sincroniza os MDs e reescreve links locais
Deploy simples	Build validado localmente e publicado via Netlify CLI
Evolução segura	Toda mudança continua passando por branch, PR e histórico

---

Estrutura

05-docs-site/
├── scripts/sync-content.mjs
├── src/content/docs/
│   ├── index.mdx
│   ├── comece-aqui/
│   ├── ecossistema/
│   ├── estrategia-produtos/
│   ├── marca/
│   ├── comercial/
│   ├── operacao/
│   ├── materiais/
│   └── repositorio/
├── src/styles/techhuman.css
├── public/materials/
└── astro.config.mjs

---

Como o conteúdo entra no portal

O script scripts/sync-content.mjs:

1. lê os MDs canônicos;
2. adiciona frontmatter para o Starlight;
3. mantém o corpo do conteúdo;
4. remove apenas o primeiro H1 duplicado na cópia gerada, porque o Starlight já renderiza o título;
5. converte links internos entre MDs para URLs do portal;
6. copia materiais HTML e assets públicos para public/materials/;
7. indica o caminho do documento canônico, sem expor link direto para o repositório.

---

Publicação

O domínio público usa Netlify Free. Para publicar:

npm run validate:custom-domain
npx netlify-cli@latest deploy --prod --dir=dist

O workflow .github/workflows/deploy-docs.yml continua validando/buildando para GitHub Pages, mas a publicação operacional em domínio próprio é feita pelo Netlify.

---

Domínio

Produção:

https://docs.techhuman.com.br/

Domínio Netlify:

https://techhuman-docs.netlify.app/

Build correto para domínio próprio:

npm run build:custom-domain

Configuração esperada:

docs.techhuman.com.br CNAME techhuman-docs.netlify.app
custom_domain=docs.techhuman.com.br
force_ssl=true

---

Separação Docs vs Playbook

Camada	Domínio	Função
Docs	docs.techhuman.com.br	Documentos integrais, fonte canônica pública e leitura profunda
Playbook	playbook.techhuman.com.br	Experiência guiada, visual e progressiva para entendimento
Site comercial	techhuman.com.br	Conversão, posicionamento público e aquisição

O Docs preserva a profundidade. O Playbook futuro reduz carga cognitiva e cria caminhos por perfil, sem copiar a documentação integral.