ADR-025: MkDocs + Material como plataforma de documentación¶
Estado: aceptado
Contexto¶
SmallCountry necesitaba una plataforma de documentación que fuera estática (sin backend), generada desde Markdown versionado en git, con soporte para múltiples idiomas, búsqueda, y desplegable sin dependencias externas. Debía alinearse con el principio 12 (conocimiento compartido) y el principio 7 (soberanía operativa).
Decisión¶
MkDocs con el tema Material for MkDocs como plataforma única de documentación para SmallCountry. El sitio se genera estáticamente desde archivos Markdown en el repositorio infra-core y se sirve vía Caddy en tonatiuh.duckdns.org.
Alternativas consideradas¶
| Opción | Por qué se descartó |
|---|---|
| Docusaurus | Mayor complejidad de configuración. Dependencia de React/Node en build. |
| Hugo | Template system menos expresivo. Comunidad más pequeña para documentación técnica. |
| Wiki.js | Requiere base de datos y backend. Viola el principio de simplicidad. |
| WordPress | Dependencia de PHP + MySQL. Superficie de ataque mayor. No es estático. |
Consecuencias¶
- ✅ 100% estático, servible desde cualquier HTTP server
- ✅ Markdown versionado en git — documentación como código (principio 1)
- ✅ Búsqueda offline, multi-idioma, accesible
- ✅ CI/CD integrado con Forgejo Actions (docs-ci.yml)
- ❌ Build requiere Python + MkDocs instalados en imagen Docker de CI
- ❌ Sin backend — no hay edición colaborativa en tiempo real