ADR-0002 · Agregación con mkdocs-multirepo-plugin

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

Contexto y problema

La documentación vive en 8+ repositorios pero debe publicarse como un solo sitio con búsqueda transversal. Hay que decidir cómo juntar los docs/ de cada repo en un build, sin duplicar contenido ni crear pasos manuales.

Opciones consideradas

1. mkdocs-multirepo-plugin: clona los repos en build time vía !import en el nav
2. Git submodules en el repo del portal
3. Copiar docs al portal vía CI de cada repo (push-based)
4. mkdocs-monorepo-plugin (requiere que todo viva en un monorepo — no es el caso)

Decisión

mkdocs-multirepo-plugin. El portal declara los repos en una línea por sistema y el build siempre trae la última versión de main — cero pasos en los repos de origen más allá del webhook de notificación. Submodules exigen actualizar punteros manualmente (el portal quedaría desactualizado por defecto); el push-based invierte la dependencia y obliga a cada repo a conocer la mecánica interna del portal.

Consecuencias

Positivas

• Agregar un sistema al portal es una línea en mkdocs.yml.
• El build siempre refleja main de cada repo: imposible publicar versiones viejas.

Negativas / deuda asumida

• El build depende de la disponibilidad de GitHub y de un token con lectura de los repos privados.
• Un repo con docs rotos rompe el build del portal completo (mitigación: el sitio publicado no se cae; ver runbook, falla frecuente n.º 1).
• Plugin de comunidad con mantenimiento moderado: revisar compatibilidad al actualizar MkDocs.