Compatibilidad del motor de documentación

Estado evaluado: 15 de agosto de 2026.

Esta página define el contrato para cambiar el motor que publica la wiki. El objetivo no es migrar por novedad, sino evitar que una actualización de MkDocs, Material o un reemplazo futuro rompa navegación, búsqueda, redirects o reproducibilidad.

Producción actual

La publicación de GitHub Pages permanece en:

• mkdocs==1.6.1
• mkdocs-material==9.7.7
• mkdocs-redirects==1.2.3
• properdocs==1.6.7 como pin transitivo reproducible

El build de producción debe seguir pasando mkdocs build --strict y python -m scripts.verify_site antes de subir el artefacto de Pages.

Material for MkDocs 9.7 está en modo de mantenimiento. Su documentación también advierte que MkDocs 2.0 no es compatible con Material for MkDocs, por lo que no se debe permitir una actualización mayor automática de MkDocs mientras esta sea la plataforma de producción.

Fuentes de referencia:

• Material for MkDocs, changelog
• Material for MkDocs y MkDocs 2.0

Perfiles web y offline

La wiki tiene dos perfiles de build deliberadamente distintos:

• mkdocs.yml es el perfil web de GitHub Pages. Conserva Instant Navigation, prefetch, progress e instant previews porque el sitio se sirve por HTTP(S).
• mkdocs.offline.yml hereda la configuración base, activa los plugins privacy y offline, elimina el enlace de repositorio y reemplaza la lista de features para excluir navigation.instant*.

La separación es necesaria porque Material documenta que Instant Navigation usa fetch, y esas solicitudes están restringidas cuando el sitio se abre directamente desde file://. El plugin offline mueve el índice de búsqueda a JavaScript y el plugin privacy materializa activos externos requeridos por el modo offline, de forma que el artefacto distribuido no dependa de una conexión en tiempo de ejecución.

Verificación reproducible:

python -m mkdocs build --strict
python -m scripts.verify_site site
python -m mkdocs build --strict -f mkdocs.offline.yml -d site-offline
python -m scripts.verify_offline_site site-offline

El perfil offline no reemplaza al de Pages. Es un segundo artefacto para consulta local y conservación.

Candidato evaluado: Zensical 0.0.54

Zensical es el sucesor desarrollado por el equipo de Material for MkDocs. La versión Zensical 0.0.54 fue publicada el 13 de agosto de 2026.

La compatibilidad existente es relevante para esta wiki porque Zensical puede interpretar configuración de proyectos MkDocs/Material y mantiene compatibilidad con Python Markdown y muchas características del tema. Eso permite evaluarlo sin reescribir el corpus.

Sin embargo, no es el motor de producción de este repositorio.

Fuentes de referencia:

• Zensical
• Compatibilidad con proyectos existentes
• Compatibilidad de plugins
• Release 0.0.54

Bloqueador actual: redirects legacy

Esta wiki conserva rutas públicas antiguas con mkdocs-redirects. No son un detalle cosmético: enlaces existentes, referencias externas y bookmarks deben continuar resolviendo después de una migración.

Al 15 de agosto de 2026, la compatibilidad con mkdocs-redirects sigue registrada por Zensical como trabajo pendiente de prioridad Tier 1 en zensical/backlog#23.

Por eso, un build exitoso de Zensical por sí solo no es suficiente para autorizar la migración. La nueva plataforma debe demostrar paridad de rutas legacy.

Gates obligatorios antes de cambiar producción

Una migración del motor sólo puede entrar a main cuando el candidato demuestre, en CI y sobre el mismo corpus:

1. build estricto sin errores ni warnings que oculten contenido inválido;
2. todas las páginas y anchors internos válidos;
3. las rutas legacy actuales siguen resolviendo al destino esperado;
4. búsqueda local funcional y sin dependencia obligatoria de servicios externos;
5. soporte del CSS y HTML usados por la portada y navegación;
6. ningún cambio en la semántica de provenance, vigencia temporal o RAG;
7. artefacto de Pages reproducible y verificable antes del deploy;
8. rollback sencillo al motor anterior durante la transición.

Hasta que todos esos gates sean verdes, Zensical debe tratarse como candidato experimental y no como reemplazo de producción.

Pin transitivo de ProperDocs

La verificación en un runner limpio muestra que mkdocs-redirects==1.2.3 declara properdocs>=1.6.5 y el resolver instala ProperDocs aunque no aparezca como comando directo de la wiki.

Por reproducibilidad, este repositorio conserva properdocs==1.6.7 como pin explícito de esa dependencia transitiva. El objetivo no es usar ProperDocs como motor alternativo, sino impedir que una versión transitiva flotante cambie el entorno de build sin revisión.

Política de actualización

• Mantener versiones del motor, plugins y dependencias transitivas sensibles fijadas explícitamente en CI.
• Revisar nuevas versiones de Material sólo por correcciones relevantes mientras permanezca en maintenance mode.
• No subir a MkDocs 2.x mientras Material siga siendo el tema de producción.
• Reevaluar Zensical cuando cambie el estado de zensical/backlog#23 o aparezca soporte equivalente de redirects.
• Hacer la migración real en un PR separado, con comparación de artefactos y rutas, nunca mezclada con cambios jurídicos del corpus.