Editor de diagramas de flujo Mermaid
Un diagrama de flujo muestra cómo avanza un proceso: qué pasos hay, dónde se bifurca y dónde vuelven a juntarse las ramas. Sirve cuando lo importante es el orden de las decisiones — un despliegue, el recorrido de una petición, un circuito de aprobación. Si lo importante es quién habla con quién y cuándo, usa un diagrama de secuencia.
Un despliegue con dos caminos de fallo
Casi todos los diagramas de flujo de este sitio empiezan con esta forma: un camino feliz recto del que se desvían los rombos de decisión. Fíjate en las comillas del penúltimo nodo. Los paréntesis dentro de una etiqueta hay que entrecomillarlos, y olvidarlo es el error más frecuente de todos.
flowchart TD
Push[Push a main] --> Lint[Análisis estático y tipos]
Lint --> Test{¿Pasan las pruebas?}
Test -->|No| Aviso[Avisar a quien hizo el commit]
Test -->|Sí| Build[Construir la imagen]
Build --> Scan{¿Escaneo sin vulnerabilidades?}
Scan -->|No| Bloqueo["Bloquear la release (revisión manual)"]
Scan -->|Sí| Deploy[Desplegar a producción]
Deploy --> Humo[Pruebas de humo]
Humo --> Fin[Release publicada]Ejemplos resueltos
1. El diagrama mínimo
Dos nodos y una flecha. `TD` va de arriba abajo y `LR` de izquierda a derecha; los diagramas más anchos que altos casi siempre se leen mejor con `LR`.
flowchart TD
Recibir[Recibir la petición] --> Responder[Enviar la respuesta]2. Una bifurcación con etiquetas
Las llaves dibujan un rombo. Lo que va entre barras verticales etiqueta la arista, no el nodo. Esa distinción vuelve a aparecer más abajo, en la sección de errores.
flowchart TD
Inicio[Recibir la petición] --> Auth{¿El token es válido?}
Auth -->|Sí| Procesar[Ejecutar el manejador]
Auth -->|No| Rechazar[Devolver 401]
Procesar --> Ok[Devolver 200]3. Que la forma signifique algo
Las formas son la manera más barata de añadir información a un diagrama de flujo. Los extremos redondeados marcan principio y fin, el rombo una decisión y el cilindro un almacén de datos.
flowchart LR
Inicio([Lanzar el proceso]) --> Leer[(Leer de Postgres)]
Leer --> Hay{¿Hay filas nuevas?}
Hay -->|No| Fin([Terminar sin cambios])
Hay -->|Sí| Transformar[/Transformar los datos/]
Transformar --> Escribir[(Escribir en S3)]
Escribir --> Fin4. Subgrafos para agrupar por responsable
Un subgrafo encierra nodos relacionados en un marco. Donde más rinde no es agrupando por etapa sino por responsable: cuando se ve qué equipo o qué servicio es dueño de cada parte, aparecen los traspasos.
flowchart TD
subgraph cliente [Navegador]
UI[Enviar el formulario]
end
subgraph api [Servicio de pedidos]
Validar[Validar la entrada]
Guardar[Guardar el pedido]
end
subgraph async [Procesos en segundo plano]
Correo[Enviar la confirmación]
Factura[Generar la factura]
end
UI --> Validar
Validar --> Guardar
Guardar --> Correo
Guardar --> Factura5. Un bucle de reintentos con tope
Los diagramas de flujo llevan bien los ciclos. Un bucle de reintentos es donde de verdad lucen, porque el dibujo deja ver de un vistazo si el bucle tiene salida de verdad.
flowchart TD
Enviar[Enviar el webhook] --> Resp{¿Respondió 2xx?}
Resp -->|Sí| Ok[Marcar como entregado]
Resp -->|No| Intentos{¿Menos de 5 intentos?}
Intentos -->|Sí| Espera[Espera exponencial]
Espera --> Enviar
Intentos -->|No| Cola[A la cola de fallidos]Referencia de sintaxis del diagrama de flujo
Todo lo de esta tabla es exclusivo del diagrama de flujo. Las flechas sobre todo: no se pueden llevar a otros tipos. El `->>` de un diagrama de secuencia aquí es un error de sintaxis.
| Sintaxis | Significado |
|---|---|
| flowchart TD | De arriba abajo. `TB` es lo mismo. El sentido habitual para leer un proceso. |
| flowchart LR | De izquierda a derecha. También existe `RL`. Para flujos anchos y poco profundos. |
| A[Texto] | Rectángulo — un paso normal. |
| A(Texto) | Rectángulo de esquinas redondeadas. |
| A([Texto]) | Forma de estadio — por convención, inicio o fin. |
| A[(Texto)] | Cilindro — un almacén de datos. |
| A{Texto} | Rombo — una decisión. |
| A[/Texto/] | Paralelogramo — entrada o salida. |
| A --> B | Flecha. |
| A --- B | Línea sin punta. |
| A -.-> B | Flecha punteada — por convención, algo asíncrono u opcional. |
| A ==> B | Flecha gruesa — por convención, el camino principal. |
| A -->|texto| B | Arista etiquetada. Si lleva paréntesis, hay que entrecomillarla. |
| A["Texto (con paréntesis)"] | Etiqueta entrecomillada — necesaria para paréntesis, comillas y cualquier carácter que sea sintaxis de forma. |
| subgraph nombre [Título] ... end | Agrupa nodos en un marco. Se cierra con `end`. |
| %% comentario | Línea de comentario. No se dibuja. |
Seis errores que de verdad rompen un diagrama de flujo
Todos reproducidos con el motor que usa este sitio (Mermaid 11.12.2). Pega la versión rota en el editor y saldrá exactamente el error descrito; la corregida se dibuja. El atajo para leer los errores de Mermaid es mirar el final: después de `got` aparece el token con el que tropezó el analizador.
Lo que ves
Parse error, termina en: got 'PS'
Por qué
Hay un paréntesis de apertura dentro de una etiqueta entre corchetes. Los paréntesis son sintaxis de forma — `A(texto)` es un nodo redondeado —, así que un paréntesis suelto dentro de los corchetes se lee como el principio de una forma.
Solución
Entrecomilla la etiqueta entera. Dentro de comillas dobles todo se trata como texto.
flowchart TD
A[Reintentar (máximo 5 veces)] --> B[Listo]flowchart TD
A["Reintentar (máximo 5 veces)"] --> B[Listo]Lo que ves
Parse error, termina en: got 'STR'
Por qué
Hay comillas dobles en mitad de la etiqueta. El analizador las toma como el principio de una cadena y se encuentra el corchete de cierre donde esperaba la comilla que cierra.
Solución
Entrecomilla toda la etiqueta y usa comillas simples dentro, o escribe el carácter como `#quot;`.
flowchart TD
A[El estado es "pendiente"] --> B[Listo]flowchart TD
A["El estado es 'pendiente'"] --> B[Listo]Lo que ves
Parse error en la línea donde nombraste un nodo
Por qué
El identificador del nodo lleva espacios. En español cuesta evitarlo, porque los nombres naturales son sintagmas: «servicio de autenticación», «base de datos de usuarios». El identificador es el token anterior a la flecha, y el espacio lo corta, así que queda una palabra suelta que el analizador no sabe dónde colocar.
Solución
Identificador de una sola palabra y el texto legible en la etiqueta. Los acentos y la ñ sí valen dentro del identificador.
flowchart TD
servicio de autenticación --> base de datosflowchart TD
auth[Servicio de autenticación] --> db[(Base de datos de usuarios)]Lo que ves
Parse error, termina en: got 'end'
Por qué
Has usado `end` como identificador de nodo. En minúsculas, `end` cierra un subgrafo, así que aparece un fin de bloque donde debería haber un nodo. Pasa más de lo que parece: al seguir ejemplos en inglés uno acaba llamando `end` al último nodo aunque el resto del diagrama esté en español.
Solución
Ponlo en mayúscula o dale otro identificador y mete la palabra en la etiqueta. `Fin` no da ningún problema.
flowchart TD
Inicio[Arrancar] --> endflowchart TD
Inicio[Arrancar] --> Fin[Terminado]Lo que ves
Parse error en una etiqueta de arista entre barras
Por qué
Hay paréntesis dentro de la etiqueta de la arista. Lo que va entre `|…|` tiene la misma restricción que la etiqueta de un nodo: ahí los paréntesis también son sintaxis, no texto.
Solución
Entrecomilla también la etiqueta de la arista.
flowchart TD
A -->|sí (siempre)| Bflowchart TD
A -->|"sí (siempre)"| BLo que ves
Lexical error on line 1. Unrecognized text.
Por qué
La dirección no es válida. Un diagrama de flujo solo admite TB, TD, BT, LR y RL; cualquier otra cosa falla en el análisis léxico, antes de leer un solo nodo. Por eso el error apunta a la línea 1 y no al sitio donde está la errata.
Solución
Usa una de las cinco. Con TD y LR se cubre casi todo.
flowchart ARRIBA
A --> Bflowchart TD
A --> BNotas sobre el dibujado
Nada de esto está copiado de la documentación: todo está medido sobre el Mermaid 11.12.2 que usa este sitio. Son los comportamientos que empiezan a importar cuando el diagrama deja de ser un juguete.
Las etiquetas solo parten por los espacios, y eso penaliza al español
Medido: una etiqueta de nodo crece a lo ancho hasta toparse con un tope de 276 píxeles de viewBox, y a partir de ahí parte en varias líneas y crece a lo alto, unos 24 píxeles por línea. Con `[Enviar correo de confirmación]` ya se llega al tope con cuatro palabras. Esto importa en español porque nuestras etiquetas son más largas que las inglesas: donde el inglés dice «Ship the order», nosotros decimos «Enviar el pedido al cliente». La consecuencia práctica es que un diagrama traducido del inglés gana altura aunque no cambie ni un nodo. El detalle que sorprende es que el corte solo ocurre en los espacios: una sola palabra de 40 caracteres no parte nunca y estira el nodo hasta 432 píxeles, deformando el diagrama entero.
La altura crece unos 105 píxeles por nodo y el ancho casi no se mueve
En un diagrama de arriba abajo, tres nodos dan un viewBox de unos 126×278. Con cuarenta se va a 135×4126: el ancho ha subido 9 píxeles y la altura se ha multiplicado por quince. Un diagrama largo es una tira estrecha que no cabe en ninguna pantalla. Para eso está el botón de centrar de la vista previa. Cuando se estira demasiado, cambiar a `flowchart LR` suele partir la proporción casi por la mitad.
Los acentos, la ñ y los signos de apertura no dan ningún problema
Comprobado: `Validación`, `Envío`, `Diseño` y `Añadir` valen como identificadores de nodo, no solo como etiquetas. Y `A[¿Pago aceptado?]` se dibuja sin entrecomillar, igual que dentro de un rombo `A{¿Pago aceptado?}`. No hace falta escribir los identificadores sin tildes ni evitar los signos de apertura: lo único que rompe un identificador es el espacio.
Las etiquetas son HTML, y por eso la exportación a PNG estuvo rota
Las etiquetas de un diagrama de flujo se dibujan como HTML de verdad dentro de un `<foreignObject>` del SVG. Por eso admiten `<br>` y algo de Markdown. Y por eso mismo el navegador se niega a volcar ese SVG a un canvas, así que durante mucho tiempo la exportación a PNG de este sitio devolvía en silencio un fichero SVG. Ahora se redibuja con etiquetas de texto SVG antes de exportar y el PNG sale bien. El precio es que la tipografía del PNG difiere mínimamente de la de la pantalla.
El tema cambia el color, nunca la geometría
El mismo diagrama con el tema claro y con el oscuro da un viewBox idéntico. Cambiar de tema no recoloca nada ni hace que una etiqueta se salga de su caja. Lo que se vea raro en oscuro se ve igual de raro en claro.
Cuándo conviene otro diagrama
Si lo que importa es quién envía qué a quién, y el orden temporal pesa más que las bifurcaciones, un diagrama de secuencia se entiende mejor y sigue entendiéndose cuando crece. Un diagrama de flujo con seis participantes metidos como nombres de nodo es un diagrama de secuencia que todavía no lo ha admitido.
Si no describes un procedimiento sino los estados por los que pasa una cosa, usa un diagrama de estados. La señal es fácil de ver: si las etiquetas de los nodos son estados — «pedido pendiente», «pedido enviado» —, es una máquina de estados; si son acciones — «validar la entrada», «enviar el correo» —, es un diagrama de flujo.
Y pasados los cuarenta nodos, siendo honestos, no hay diagrama que lo salve. O lo partes en varios con una entrada común, o aceptas que lo que intentas explicar es demasiado complejo para un solo dibujo. Eso último también es información útil.
Otros tipos de diagrama
Escrito por Dominik Malsch · Última actualización: