Crear diagramas siempre ha sido una de mis partes menos favoritas de la documentación. Perdía horas moviendo cuadros y aun así terminaba con algo que parecía amateur. Eso cambió cuando descubrí Mermaid. En esta publicación, comparto cómo uso Mermaid CLI para crear diagramas usando solo texto, y cómo las herramientas de inteligencia artificial han transformado y agilizado completamente este proceso.

¿Qué es Mermaid?

Mermaid es una herramienta gratuita y de código abierto que convierte texto en diagramas, similar a cómo Markdown convierte texto en contenido formateado. Es completamente gratuita bajo la licencia MIT, por lo que puedes usarla para trabajo o asuntos personales sin preocuparte por los costos de licencia. Puede usarse para crear todo tipo de diagramas, como:

Diagramas de flujo
Diagramas de secuencia
Diagramas de clases
Diagramas entidad-relación
Gráficos de Gantt
Gráficos circulares
Mapas de viaje del usuario
Gráficos de Git
Diagramas de estado
Y muchos más

Lo que más me gusta es que ya no tengo que arrastrar cuadros. Simplemente escribo texto y Mermaid crea el diagrama. Después de años luchando con herramientas de diagramación tradicionales, este enfoque se siente como una revelación.

Primeros Pasos con Mermaid CLI

Empecé a usar Mermaid en el navegador, pero la versión CLI (Interfaz de Línea de Comandos) es donde ocurre la verdadera magia. Te permite convertir tus diagramas de texto en archivos de imagen reales que puedes incluir en documentos, presentaciones o donde quieras. Y es súper fácil de usar.

La sintaxis básica para usar Mermaid CLI es:

npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png

Este comando:

npx @mermaid-js/mermaid-cli: Ejecuta la herramienta Mermaid CLI sin necesidad de una instalación global
-i diagram.mmd: Especifica el archivo de entrada que contiene tu definición de diagrama Mermaid
-o diagram.png: Establece el nombre del archivo de salida y el formato (PNG en este caso)

También puedes generar archivos SVG que son escalables y perfectos para uso web:

npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

También puedes previsualizar rápidamente tu código Mermaid en línea usando herramientas como MermaidChart, lo cual es genial para probar y compartir diagramas sin instalar nada.

Creando tu Primer Diagrama Mermaid

Empecemos con un diagrama de flujo simple. Crea un archivo llamado flowchart.mmd con este contenido:

flowchart TD
A[Inicio] --> B{Decisión}
B -->|Sí| C[Proceso 1]
B -->|No| D[Proceso 2]
C --> E[Fin]
D --> E

Ahora, genera una imagen PNG de este diagrama:

npx @mermaid-js/mermaid-cli -i flowchart.mmd -o flowchart.png

Esto creará un diagrama de flujo limpio y de aspecto profesional que muestra un proceso de decisión simple, como este:

Diagrama de flujo simple que muestra un proceso de decisión

Puedes usar este mismo enfoque para cualquier tipo de diagrama que Mermaid soporte.

Por ejemplo, si necesitas visualizar una arquitectura de sistema (como hice recientemente), podrías crear algo como esto:

flowchart TD
Cliente([Navegador Web]) --HTTP/HTTPS--> LB[Balanceador de Carga]
LB --> API1[Servidor API 1]
LB --> API2[Servidor API 2]
API1 --> DB[(Base de Datos)]
API2 --> DB
API1 --> Cache[(Caché Redis)]
API2 --> Cache

Lo que produce este diagrama:

Diagrama de arquitectura que muestra servidores web, balanceador de carga y base de datos

Cómo la IA Potencia la Creación de Diagramas

Aquí es donde la inteligencia artificial se convierte en un punto de inflexión. En lugar de escribir diagramas Mermaid manualmente, las herramientas de IA como Cursor y Windsurf pueden analizar descripciones de texto y generar automáticamente definiciones de diagramas para ti.

Recientemente tuve que crear un diagrama de arquitectura para un proyecto de AWS + Drupal con una arquitectura compleja. Sin IA, esto habría llevado un tiempo considerable mapear todos los componentes y conexiones. En cambio, alimenté las especificaciones del proyecto al asistente de IA de Cursor, le pedí que extrajera los componentes del sistema y sus relaciones, y obtuve código Mermaid que me ayudó a crear el diagrama de manera más eficiente.

Usando la IA de Cursor para Generar Diagramas

Cursor es un IDE con una potente IA que entiende tanto el código como el lenguaje natural. Su capacidad para interpretar descripciones técnicas y convertirlas en sintaxis estructurada de Mermaid es notable. Aquí está mi flujo de trabajo típico:

Copia el texto relevante que describe el concepto que deseas visualizar
Usa una indicación como: "Genera un diagrama Mermaid basado en esta descripción"
Cursor analizará el texto y generará la sintaxis Mermaid apropiada
Guarda el código Mermaid generado en un archivo .mmd
Usa Mermaid CLI para convertirlo en una imagen

Por ejemplo, podrías indicarle a Cursor con instrucciones como:

"Crea un diagrama de flujo Mermaid que muestre un proceso de registro de usuario"
"Genera un diagrama de secuencia Mermaid para este flujo de solicitud de API"
"Convierte esta línea de tiempo del proyecto en un gráfico de Gantt Mermaid"
"Crea un diagrama de clases Mermaid a partir de esta descripción del modelo de dominio"

En segundos, tendrás un diagrama Mermaid completo que representa con precisión tu concepto.

Llevándolo Más Allá con la IA de Windsurf

Windsurf (de Codeium) aprovecha la IA para llevar la automatización de diagramas aún más lejos. Sus modelos de IA pueden analizar bases de código completas o conjuntos de documentación para crear scripts que:

Escanean archivos de texto en busca de descripciones que puedan visualizarse
Extraen elementos y relaciones clave
Generan la sintaxis Mermaid apropiada según el tipo de contenido
Ejecutan automáticamente Mermaid CLI para crear imágenes de diagramas
Incluyen estos diagramas en tus documentos

Esto crea un flujo de trabajo de documentación continuo donde tus diagramas se mantienen sincronizados con tu contenido escrito. La IA puede detectar cuándo tu código o documentación cambian lo suficiente como para justificar actualizaciones de diagramas, haciendo que todo el proceso sea casi automático.

Tipos de Diagramas Avanzados

Mermaid soporta muchos tipos de diagramas más allá de los diagramas de flujo simples. Aquí hay algunos útiles para la documentación de arquitectura:

Diagramas de Secuencia

Perfectos para ilustrar cómo interactúan los componentes a lo largo del tiempo:

sequenceDiagram
participant Usuario
participant API
participant BaseDeDatos

Usuario->>API: GET /productos
API->>BaseDeDatos: Consultar productos
BaseDeDatos-->>API: Devolver resultados
API-->>Usuario: Respuesta JSON

Lo que produce este diagrama de secuencia:

Diagrama de secuencia que muestra el flujo de solicitud de API entre Usuario, API y Base de Datos

Diagramas de Clases

Ideales para mostrar el diseño orientado a objetos:

classDiagram
class Pedido {
    +String id
    +Date createdAt
    +OrderStatus status
    +calcularTotal()
}
class Cliente {
    +String id
    +String nombre
    +String email
    +realizarPedido()
}
Cliente "1" -- "muchos" Pedido: realiza

Lo que produce este diagrama de clases:

Diagrama de clases que muestra las clases Cliente y Pedido con su relación

Diagramas Entidad-Relación

Geniales para el diseño de bases de datos:

erDiagram
CLIENTE ||--o{ PEDIDO : realiza
PEDIDO ||--|{ LINEA_PEDIDO : contiene
CLIENTE }|..|{ DIRECCION_ENVIO : usa

Lo que produce este diagrama entidad-relación:

Diagrama Entidad-Relación que muestra las relaciones de cliente, pedido, línea de pedido y dirección de envío

Ejemplos Prácticos

Mermaid CLI se puede utilizar para diversas necesidades de visualización, incluida la documentación de arquitectura de sistemas (como se mencionó anteriormente), pero también para:

Planificación de Proyectos

Para la planificación de proyectos, puedes crear un diagrama de Gantt que muestre fases y dependencias:

gantt
title Cronograma del Proyecto
dateFormat  YYYY-MM-DD
section Investigación
Recopilación de requisitos :a1, 2025-01-01, 10d
Investigación de mercado       :after a1, 7d
section Desarrollo
Desarrollo Frontend  :b1, 2025-01-18, 14d
Desarrollo Backend   :b2, 2025-01-18, 21d
section Pruebas
Pruebas de integración   :c1, after b1 b2, 7d
Aceptación del usuario       :c2, after c1, 7d

Lo que produce esta visualización de cronograma:

Diagrama de Gantt que muestra el cronograma del proyecto con fases de desarrollo

Documentación de Procesos

Para documentar procesos de negocio, Mermaid puede crear diagramas de flujo claros:

flowchart TD
Inicio([Pedido del cliente]) --> A{¿Stock disponible?}
A -->|Sí| B[Procesar pago]
A -->|No| C[Proceso de pedido pendiente]
B --> D[Enviar producto]
C --> E[Notificar al cliente]
D & E --> Fin([Pedido completado])

Lo que produce este diagrama de flujo de proceso:

Diagrama de flujo de proceso que muestra un flujo de trabajo de pedido del cliente

Posibilidades Futuras con IA y Automatización

La combinación de Mermaid CLI y herramientas de IA abre posibilidades emocionantes para la automatización de la documentación. Imagino un sistema que podría:

Monitorear archivos de documentación en busca de cambios
Usar IA para identificar contenido que podría beneficiarse de la visualización
Generar sintaxis Mermaid apropiada basada en el contenido
Ejecutar automáticamente Mermaid CLI para crear imágenes de diagramas actualizadas
Incrustar inteligentemente los diagramas en la documentación con el contexto adecuado

Tal configuración mantendría los diagramas sincronizados con la documentación sin intervención manual. Aunque aún no he construido este sistema, las herramientas de IA actuales y Mermaid CLI lo hacen completamente posible.

Consejos para Mejores Diagramas

Usa formas significativas: Mermaid ofrece varias formas de nodos para distinguir diferentes tipos de componentes (bases de datos, servicios, sistemas externos)
Añade color para mayor claridad: Usa colores para agrupar componentes relacionados o resaltar elementos importantes
Mantenlo simple: Evita saturar los diagramas; crea múltiples diagramas enfocados en lugar de uno complejo
Usa subgráficos: Agrupa componentes relacionados usando subgráficos para mostrar límites lógicos
Añade títulos y descripciones: Haz que tus diagramas se expliquen por sí mismos con títulos claros y descripciones breves

En Resumen

Mermaid ofrece un enfoque práctico para la creación de diagramas que se integra bien con los flujos de trabajo de desarrollo. La naturaleza basada en texto de los diagramas Mermaid los hace amigables para el control de versiones y más fáciles de mantener que los formatos de diagramación tradicionales.

Cuando se combina con herramientas de IA, el proceso se vuelve aún más eficiente. Estas herramientas pueden ayudar a generar código de diagrama a partir de descripciones, haciéndolo accesible incluso para aquellos sin un conocimiento técnico profundo.

Aquí hay algunas reflexiones finales sobre el uso de Mermaid:

Curva de aprendizaje: La sintaxis es relativamente simple de aprender, especialmente si ya estás familiarizado con markdown u otros formatos basados en texto.
Integración: Los diagramas Mermaid funcionan en muchas plataformas, incluidas GitHub, Notion y otros sistemas de documentación.
Costo: Como herramienta de código abierto con licencia MIT, Mermaid es de uso gratuito para cualquier propósito.
Eficiencia: La creación de diagramas basada en texto puede ser más rápida que la diagramación tradicional una vez que te familiarizas con la sintaxis.
Facilidad de configuración: Usar npx para ejecutar Mermaid CLI elimina los problemas de instalación.

Si buscas mejorar tu proceso de documentación, considera probar Mermaid para tu próximo proyecto. La capacidad de crear diagramas profesionales directamente a partir de descripciones de texto, con la asistencia potencial de herramientas de IA, podría transformar la forma en que abordas la visualización en tu trabajo.

Documentation

Automatización de la Creación de Diagramas con Mermaid CLI y Herramientas de IA