ADR-002 — MkDocs com tema Material para documentação¶
Status: ✅ Aceito Data: 2026-06-10
Contexto¶
O repositório AMia-Roadmap contém documentação técnica e de produto que precisa ser: - Publicada como site navegável e pesquisável - Mantida por múltiplos perfis de usuário (desenvolvedores, POs, arquitetos) - Versionada em Git como código de primeira classe - Deployada automaticamente via CI/CD
As alternativas consideradas foram: 1. MkDocs + tema Material — gerador de site estático baseado em Markdown 2. Docusaurus — gerador React, mais flexível mas mais complexo de manter 3. GitBook — SaaS, fácil de usar mas com vendor lock-in e custos 4. Confluence — wiki corporativo, bom para integração com Jira/ADO mas sem versionamento Git nativo 5. VitePress — alternativa moderna ao VuePress, focada em documentação técnica
Decisão¶
Adotar MkDocs com tema Material como framework de documentação para o repositório AMia-Roadmap.
Justificativa¶
- MkDocs + Material é o padrão de facto para documentação técnica em Python — amplamente adotado e com extensa comunidade
- Tema Material oferece visual profissional, suporte a busca, modo escuro e navegação responsiva out-of-the-box
- Pipeline de publicação simples:
pip install -r requirements.txt && mkdocs build— sem build steps complexos - Integração nativa com Azure Static Web Apps para hospedagem de sites estáticos
strict: truevalida links internos no build — prevenção automática de links quebrados
Consequências¶
Positivas:
- Documentação como código — versionada, revisável, deployada via CI/CD
- Build reproduzível com requirements.txt versionado
- Suporte nativo a busca, Mermaid, admonitions e code highlighting
- Site publicado automaticamente a cada push na branch master
Negativas: - Requer Python e pip para build local (adiciona dependência ao onboarding de novos membros) - Funcionalidades dinâmicas (comentários, formulários) requerem integrações externas - O tema Material em versão gratuita tem algumas limitações de features avançadas (Insiders)