ADR-0001 · MkDocs Material como generador del portal

• Estado: aceptado
• Decisores: equipo DevOps Compulandia
• Fecha de la decisión: 2026-08-10

Contexto y problema

El épico EP-DOC define documentación docs-as-code en cada repo, consultable desde un portal unificado con búsqueda en español. Se necesita un generador de sitio estático que consuma Markdown plano de múltiples repos, sin obligar a los desarrolladores a aprender otra sintaxis ni a mantener una aplicación.

Opciones consideradas

1. MkDocs + tema Material
2. Docusaurus
3. Centralizar en Outline (descartado ya en ADR-0001 de docs-standard)

Decisión

MkDocs Material. Consume Markdown puro (el mismo que se lee en GitHub), la búsqueda client-side soporta español de fábrica, el ecosistema de plugins cubre la agregación multirepo, y la configuración es un único YAML. Docusaurus (React/MDX) agrega un stack de frontend que nadie del equipo necesita mantener para un sitio de documentación; su ventaja (componentes interactivos) no aplica a este caso de uso.

Consecuencias

Positivas

• Cualquier dev ejecuta mkdocs serve local sin conocer el portal.
• Markdown puro: los docs se leen igual de bien en GitHub que en el portal.
• Mermaid, modo oscuro y búsqueda en español resueltos por el tema.

Negativas / deuda asumida

• Sin componentes interactivos: si algún día se necesita una página dinámica, no es el vehículo.
• La búsqueda es client-side: con decenas de repos el índice crece y habrá que medir el peso de la página.