¿Alguna vez has actualizado un archivo Markdown con un nuevo diagrama de Mermaid y, al subirlo, te has encontrado con un bloque de código roto o un diagrama que simplemente no se renderiza? En la documentación técnica, un diagrama mal formado no es solo un error visual; es una pérdida de información que rompe el flujo de lectura.
En el proyecto FrikiTeam utilizamos Mermaid para mantener nuestra documentación viva y visual. Pero para que esto no se convierta en un caos de sintaxis rota, necesitamos procesos de verificación. En esta guía te explico cómo validar tus diagramas y cómo automatizar este chequeo en nuestro pipeline de CI para que nadie rompa la documentación por accidente.
Scripts de verificación
No queremos depender de la suerte para saber si un diagrama es válido. Para eso, contamos con una herramienta interna diseñada específicamente para esta tarea.
Existe internal/mermaid/tools/check_diagrams.py que se puede usar para validar la sintaxis de los diagramas. Puedes ejecutarlo localmente con el siguiente comando:
python3 internal/mermaid/tools/check_diagrams.py
Nota: Si el script devuelve un error o está vacío, documenta su comportamiento y añade un test en CI.
Mejores prácticas
Hacer diagramas es fácil, pero hacer diagramas que sean útiles y mantenibles es un arte. Para mantener la calidad de la documentación de FrikiTeam, sigue estas pautas:
- Claridad ante todo: Escribe diagramas claros y evita dependencias del tamaño del contenedor.
- Documenta la lógica: Añade comentarios cuando la lógica del diagrama sea compleja para que otros desarrolladores entiendan el flujo.
- Sigue la guía: Usa los ejemplos de
internal/mermaid/diagramas_guia.mdcomo referencia para mantener la consistencia visual.
Integración en CI
Para evitar que los diagramas corruptos lleguen a producción, la verificación no puede ser un proceso manual. Debemos integrar este chequeo directamente en nuestro flujo de trabajo.
La idea es añadir un paso que ejecute la verificación de diagramas como parte del workflow (antes de mkdocs build). Aquí tienes un ejemplo de cómo debería verse en tu archivo de configuración:
# ejemplo: steps
- name: Verificar diagramas
run: python3 internal/mermaid/tools/check_diagrams.py
Problemas comunes
Incluso con automatización, te puedes encontrar con algún tropiezo. Aquí tienes los dos escenarios más habituales y cómo solucionarlos:
- Diagrama no se renderiza: Lo primero es validar la sintaxis mediante el script o revisar la consola del navegador para ver si hay errores de JavaScript.
- Colisión de estilos: Si el diagrama se ve «raro» o con colores extraños, revisa
docs/stylesheets/extra.css.
Si prefieres que implemente una versión mínima del check_diagrams.py para validar la existencia de bloques mermaid en los md, lo puedo hacer y añadir la configuración en CI (opcional).