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 GitHub Pages 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
        ↓
GitHub Pages / 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 e publicado por workflow no repo distribuidor
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 GitHub Pages no repo distribuidor TECH-HUMAN/techhuman-docs. Para validar a mesma build localmente:

npm run validate:custom-domain

O workflow TECH-HUMAN/techhuman-docs/.github/workflows/deploy-pages.yml busca este repo canônico via deploy key read-only, executa a validação e publica o artifact no GitHub Pages.

---

Domínio

Produção:

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

Repo distribuidor:

https://github.com/TECH-HUMAN/techhuman-docs

Build correto para domínio próprio:

npm run build:custom-domain

Configuração esperada:

docs.techhuman.com.br CNAME tech-human.github.io
GitHub Pages custom_domain=docs.techhuman.com.br
https_enforced=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 reduz carga cognitiva e cria caminhos por perfil, sem copiar a documentação integral.