Mermaid: diagramas de flujo como código

Qué es Mermaid

Mermaid es una biblioteca de JavaScript, publicada por primera vez en 2014, que convierte una descripción en texto en un diagrama. Admite diagramas de flujo, de secuencia, de estados, diagramas de Gantt y otros. Un diagrama de flujo mínimo se ve así:

flowchart TD
  A([Pedido recibido]) --> B[Comprobar stock]
  B --> C{¿Hay stock?}
  C -->|Sí| D[Enviar pedido]
  C -->|No| E[Avisar al cliente]

El motor de renderizado se ocupa de las formas, las posiciones y las flechas. Tú solo describes la estructura.

Por qué escribir diagramas como código

• Control de versiones: el diagrama es texto, así que los cambios aparecen en los diffs y las revisiones de código.
• Sin archivos binarios: no hay que volver a exportar nada cuando cambia el proceso, basta con editar una línea.
• Vive con la documentación: en un README, una página de wiki o un registro de decisiones de arquitectura.
• Se muestra donde ya trabaja el equipo, sin complementos en muchas plataformas.

La contrapartida es el control: la maquetación es automática y no puedes colocar una caja exactamente donde quieras. Para la mayoría de la documentación, es más una ventaja que una limitación.

Dónde se muestra Mermaid

GitHub y GitLab muestran los bloques de código Mermaid en archivos Markdown, issues y pull o merge requests; consulta Mermaid en GitHub y GitLab. Notion y Obsidian también lo admiten de forma nativa, y muchos generadores de documentación ofrecen complementos; consulta Mermaid en Notion, Obsidian y herramientas de documentación.

Mermaid frente a las herramientas de dibujo

Las herramientas de dibujo y las pizarras son mejores para bocetos libres, pósteres de arquitectura y todo aquello en lo que la posición tiene significado. Mermaid es mejor para diagramas con estructura (pasos, decisiones, responsables), mantenidos por varias personas y que deben estar sincronizados con un texto. Regla práctica: si el diagrama se actualizará más de una vez y su maquetación no tiene que ser perfecta al píxel, escríbelo como código.

Aprender la sintaxis

Los diagramas de flujo solo necesitan unos pocos elementos: una dirección, nodos con su forma y flechas con una etiqueta opcional. La chuleta de sintaxis de Mermaid los recoge, y subgrafos y estilos explica cómo agrupar los pasos por responsable y resaltar partes del diagrama.

De una descripción a Mermaid

Escribir Mermaid a mano es rápido para diagramas pequeños y tedioso para los grandes. Otra opción es describir el proceso en lenguaje natural, dejar que un generador de diagramas de flujo con IA construya el diagrama y exportarlo a Mermaid. Flowchartio exporta un archivo flowchart TD en el que cada responsable se convierte en un subgrafo, listo para pegar en un README.

¿Mermaid o imagen?

Mermaid encaja con documentación que cambia y vive en herramientas de texto. Las presentaciones, los PDF y los correos siguen necesitando imágenes. La comparación de PNG, SVG y Mermaid te ayuda a elegir. Para documentación de software en general, incluidas las integraciones de API, consulta diagramas de flujo para API y software.