Introducción rápida y hoja de trucos de diagramas Mermaid para desarrolladores
Diagramas como código, sin el drama.
Mermaid es una herramienta de diagramación basada en texto para quienes prefieren escribir diagramas en lugar de arrastrar cajas en un lienzo. Utiliza una sintaxis similar a Markdown para describir diagramas de flujo, diagramas de secuencia, diagramas de clases, máquinas de estados, líneas de tiempo, diagramas de Gantt, diagramas de entidad-relación y más.
Para un blog técnico, Mermaid es un valor predeterminado muy bueno. Los diagramas viven junto al artículo, se pueden revisar en Git y son fáciles de actualizar cuando el sistema cambia. Los diagramas de imagen estática se ven bien hasta el primer cambio de arquitectura. Los diagramas de Mermaid no son perfectos, pero envejecen mucho mejor.
Esta guía es una introducción rápida y un resumen de referencia (cheatsheet) práctico de Mermaid para desarrolladores, redactores técnicos y propietarios de sitios Hugo. Es parte del hub de Herramientas de Documentación en 2026: Markdown, LaTeX, PDF y Flujos de Trabajo de Impresión.
¿Qué es Mermaid?
Mermaid es una sintaxis de diagrama como código. Escribes un pequeño bloque de texto y Mermaid lo renderiza como un diagrama.
Un diagrama básico de Mermaid se ve así:
este código:
```mermaid
flowchart TD
A[Escribir Markdown] --> B[Agregar bloque Mermaid]
B --> C[Renderizar página]
C --> D[Publicar diagrama]
```
Produce este diagrama:
La idea importante es simple: la fuente del diagrama es texto plano. Eso lo hace buscable, revisable, portátil y fácil de mantener junto con la documentación que explica.
¿Por qué usar Mermaid en un blog técnico?
Mermaid es útil cuando tu artículo necesita más que prosa pero menos que una herramienta de diseño completa.
Usa Mermaid cuando quieras explicar:
- Flujos de solicitud y respuesta
- Pipelines de despliegue
- Dependencias de servicios
- Transiciones de estado
- Relaciones de base de datos
- Recorridos de usuario
- Pasos de compilación
- Lógica de decisiones
- Líneas de tiempo de proyectos
No usaría Mermaid para cada visualización. Las capturas de pantalla, los bocetos de arquitectura dibujados a mano y los diagramas de marketing pulidos aún tienen su lugar. Pero para la documentación de ingeniería, Mermaid suele ser la opción más mantenible.
Inicio Rápido de Mermaid
Uso Básico en Markdown
En Markdown, usa un bloque de código delimitado con mermaid como lenguaje:
```mermaid
flowchart LR
A[Inicio] --> B[Proceso]
B --> C[Finalizado]
```
Muchas plataformas entienden este formato directamente. mermaid es uno de los identificadores de lenguaje especiales —junto con diff, geojson y otros— que ciertos renderizadores tratan como un tipo de bloque de primera clase en lugar de simple resaltado de sintaxis. Para un desglose completo de la sintaxis de bloques delimitados e identificadores de lenguaje soportados, consulta la Guía de Bloques de Código en Markdown. Para Hugo, la renderización depende de tu tema o configuración del sitio. Más sobre eso más adelante.
Prueba los Diagramas Antes de Publicar
El flujo de trabajo más sencillo es:
- Escribe el diagrama en tu archivo Markdown.
- Pégalo en un editor en vivo de Mermaid o en una vista previa local.
- Corrige errores de sintaxis.
- Envía el código fuente de Markdown al repositorio.
- Verifica la página renderizada final.
Esto evita el problema clásico donde un diagrama funciona en un renderizador pero falla en otro debido a un pequeño detalle de sintaxis.
Sintaxis de Diagramas de Flujo
Los diagramas de flujo son el tipo de diagrama de Mermaid más común. Úsalos para flujos de trabajo, algoritmos, árboles de decisión y pasos del sistema.
Diagrama de Flujo Básico
este código:
```mermaid
flowchart TD
A[El usuario abre el sitio web] --> B{¿El usuario ha iniciado sesión?}
B -->|Sí| C[Mostrar panel de control]
B -->|No| D[Mostrar página de inicio de sesión]
```
Produce este diagrama:
Direcciones del Diagrama de Flujo
Los diagramas de flujo de Mermaid soportan varias direcciones:
TD - de arriba a abajo
TB - de arriba a abajo
BT - de abajo a arriba
LR - de izquierda a derecha
RL - de derecha a izquierda
Ejemplo:
este código:
```mermaid
flowchart LR
Navegador --> CDN
CDN --> ServidorWeb
ServidorWeb --> BaseDeDatos
```
Produce este diagrama:
Para artículos de blog, LR suele ser más fácil de leer para diagramas de arquitectura. Para procesos paso a paso, TD suele ser mejor.
Formas de Nodo Comunes
este código:
```mermaid
flowchart TD
A[Rectángulo]
B(Rectángulo redondeado)
C{Decisión}
D((Círculo))
E[(Base de Datos)]
F[[Subrutina]]
```
Produce este diagrama:
Flechas en Diagramas de Flujo
este código:
```mermaid
flowchart LR
A --> B
B --- C
C -.-> D
D ==> E
E -- Etiqueta --> F
```
Produce este diagrama:
Subgráficos
Usa subgráficos para agrupar partes relacionadas de un sistema.
este código:
```mermaid
flowchart LR
subgraph Cliente
Navegador
end
subgraph Backend
API
Worker
end
subgraph Almacenamiento
DB[(PostgreSQL)]
Cache[(Redis)]
end
Navegador --> API
API --> DB
API --> Cache
API --> Worker
```
Produce este diagrama:
Los subgráficos son potentes, pero úsalos con cuidado. Un diagrama con seis subgráficos y veinte flechas suele ser señal de que el artículo necesita dos diagramas más pequeños.
Sintaxis de Diagramas de Secuencia
Los diagramas de secuencia muestran la comunicación entre actores o servicios a lo largo del tiempo.
este código:
```mermaid
sequenceDiagram
participant Usuario
participant Aplicación
participant API
participant BaseDeDatos
Usuario->>Aplicación: Hacer clic en iniciar sesión
Aplicación->>API: POST /login
API->>BaseDeDatos: Validar credenciales
BaseDeDatos-->>API: Registro de usuario
API-->>Aplicación: Token de acceso
Aplicación-->>Usuario: Mostrar panel de control
```
Produce este diagrama:
Flechas Comunes en Secuencias
-> Línea sólida sin flecha
--> Línea punteada sin flecha
->> Línea sólida con flecha
-->> Línea punteada con flecha
-x Línea sólida con cruz
--x Línea punteada con cruz
Barras de Activación
Las barras de activación hacen más claro cuándo un participante está realizando trabajo.
este código:
```mermaid
sequenceDiagram
participant Cliente
participant Servidor
Cliente->>Servidor: Solicitar datos
activate Servidor
Servidor-->>Cliente: Respuesta
deactivate Servidor
```
Produce este diagrama:
Alternativas y Condiciones
este código:
```mermaid
sequenceDiagram
participant Usuario
participant API
participant Pago
Usuario->>API: Enviar pedido
alt El pago tiene éxito
API->>Pago: Cobrar tarjeta
Pago-->>API: Aprobado
API-->>Usuario: Pedido confirmado
else El pago falla
Pago-->>API: Rechazado
API-->>Usuario: Mostrar error
end
```
Produce este diagrama:
Los diagramas de secuencia son excelentes para artículos sobre APIs. No solo muestran qué componentes existen, sino cómo se comunican entre sí.
Sintaxis de Diagramas de Clases
Los diagramas de clases son útiles para modelos de dominio y relaciones de objetos.
este código:
```mermaid
classDiagram
class Usuario {
+string id
+string email
+login()
+logout()
}
class Pedido {
+string id
+float total
+submit()
}
Usuario "1" --> "*" Pedido
```
Produce este diagrama:
Relaciones entre Clases
<|-- Herencia
*-- Composición
o-- Agregación
--> Asociación
-- Enlace
..> Dependencia
..|> Realización
Ejemplo:
este código:
```mermaid
classDiagram
Animal <|-- Perro
Animal <|-- Gato
Usuario "1" --> "*" Pedido
Pedido *-- ItemDePedido
```
Produce este diagrama:
Los diagramas de clases pueden volverse ruidosos rápidamente. En un artículo de blog, prefiere un fragmento pequeño del dominio sobre un modelo completo de la aplicación.
Sintaxis de Diagramas de Estado
Los diagramas de estado explican cómo algo cambia a lo largo del tiempo.
este código:
```mermaid
stateDiagram-v2
[*] --> Borrador
Borrador --> Revisión: enviar
Revisión --> Publicado: aprobar
Revisión --> Borrador: solicitar cambios
Publicado --> Archivado: archivar
Archivado --> [*]
```
Produce este diagrama:
Usa diagramas de estado para:
- Ciclos de vida de pedidos
- Estados de despliegue
- Flujos de autenticación
- Estado de trabajos en segundo plano
- Flujos de trabajo de publicación de contenido
Los diagramas de estado son infravalorados. A menudo explican la lógica de negocio mejor que un párrafo largo.
Sintaxis de Diagramas de Entidad-Relación
Los diagramas de entidad-relación son útiles para modelos de base de datos.
este código:
```mermaid
erDiagram
USUARIO ||--o{ PEDIDO : realiza
PEDIDO ||--|{ ITEM_PEDIDO : contiene
PRODUCTO ||--o{ ITEM_PEDIDO : aparece_en
USUARIO {
string id
string email
}
PEDIDO {
string id
datetime creado_en
}
PRODUCTO {
string id
string nombre
}
```
Produce este diagrama:
Marcadores de Relación en ER
|| exactamente uno
o| cero o uno
}| uno o más
}o cero o más
Los diagramas ER funcionan mejor cuando explican relaciones, no cada columna. Mantén los detalles de implementación en migraciones o documentación de esquemas.
Sintaxis de Diagramas de Gantt
Los diagramas de Gantt son útiles para líneas de tiempo de proyectos.
este código:
```mermaid
gantt
title Plan de Migración de Documentación
dateFormat YYYY-MM-DD
section Planificación
Auditoría de docs actuales :a1, 2026-06-01, 5d
Definir estructura :a2, después de a1, 3d
section Escritura
Reescribir guías :b1, después de a2, 10d
Revisión y publicación :b2, después de b1, 4d
```
Produce este diagrama:
Los diagramas de Gantt son útiles en publicaciones de planificación interna, pero pueden envejecer rápidamente. Úsalos cuando la línea de tiempo en sí sea el punto principal.
Sintaxis de Línea de Tiempo
Las líneas de tiempo son buenas para historias de lanzamientos, informes de incidentes y resúmenes de proyectos.
este código:
```mermaid
timeline
title Evolución de la API
2024 : API REST lanzada
2025 : Webhooks agregados
2026 : Streaming de eventos introducido
```
Produce este diagrama:
Usa una línea de tiempo cuando el orden importe más que la dependencia. Si lo que te importa es la secuencia de eventos más que cómo se conectan causalmente, una línea de tiempo mantiene el enfoque donde corresponde y permanece fácil de leer de un vistazo.
Sintaxis de Gráficos de Torta
Los gráficos de torta están soportados, pero ten cuidado. Son fáciles de leer cuando solo hay pocas categorías y los valores son claramente diferentes.
este código:
```mermaid
pie title Tiempo de Compilación por Paso
"Instalar dependencias" : 35
"Ejecutar pruebas" : 45
"Compilar activos" : 20
```
Produce este diagrama:
Consejo de opinión: si los valores están cerca o hay más de cinco categorías, usa una tabla en su lugar. Una tabla bien formateada comunica números precisos más honestamente que un gráfico de torta donde los segmentos parecen casi idénticos.
Sintaxis de Gráficos de Git
Los gráficos de Git pueden explicar estrategias de ramificación y flujos de lanzamiento.
este código:
```mermaid
gitGraph
commit
branch feature
checkout feature
commit
commit
checkout main
merge feature
commit
```
Produce este diagrama:
Esto es útil para artículos sobre flujos de trabajo de Git, desarrollo basado en trunk, ramas de lanzamiento y correcciones urgentes. Si necesitas una referencia rápida de los comandos de ramificación subyacentes, la Hoja de Referencia de GIT cubre los más comunes junto con flujos de trabajo de merge y rebase.
Hoja de Referencia de Mermaid
Tipos de Diagrama
flowchart TD
sequenceDiagram
classDiagram
stateDiagram-v2
erDiagram
gantt
timeline
pie
gitGraph
mindmap
journey
Básicos de Diagramas de Flujo
flowchart TD
A[Texto] --> B[Texto]
A -->|Etiqueta| B
A -.-> B
A ==> B
A --- B
Formas de Diagramas de Flujo
A[Rectángulo]
A(Redondeado)
A{Decisión}
A((Círculo))
A[(Base de Datos)]
A[[Subrutina]]
A>Bandera]
Básicos de Diagramas de Secuencia
sequenceDiagram
participant A
participant B
A->>B: Mensaje
B-->>A: Respuesta
activate B
deactivate B
Bloques de Secuencia
alt condición
else otra condición
end
opt paso opcional
end
loop cada ítem
end
par tarea paralela
and otra tarea
end
Básicos de Diagramas de Clases
classDiagram
class Usuario
class Pedido
Usuario --> Pedido
Usuario "1" --> "*" Pedido
Básicos de Diagramas de Estado
stateDiagram-v2
[*] --> Inactivo
Inactivo --> Ejecutando
Ejecutando --> Finalizado
Finalizado --> [*]
Básicos de Diagramas ER
erDiagram
USUARIO ||--o{ PEDIDO : realiza
PEDIDO ||--|{ ITEM_PEDIDO : contiene
Comentarios
Mermaid soporta comentarios con %%.
este código:
```mermaid
flowchart TD
%% Este es un comentario
A --> B
```
Produce este diagrama:
Usando Mermaid en Hugo
El contenido de Hugo suele escribirse en Markdown, por lo que Mermaid encaja naturalmente en un blog técnico basado en Hugo. La configuración exacta depende de tu tema y configuración de renderización de Markdown.
El patrón de creación de contenido sigue siendo el mismo:
```mermaid
flowchart LR
Markdown --> Hugo
Hugo --> HTML
HTML --> Navegador
```
Si tu tema de Hugo ya soporta Mermaid, esto puede renderizarse sin trabajo extra. Si no es así, generalmente necesitas un gancho de renderizado, shortcode, parcial o configuración del tema que cargue Mermaid en páginas que contengan diagramas de Mermaid.
Una configuración práctica de Hugo debería apuntar a estas reglas:
- Mantén el código fuente de Mermaid dentro de los artículos normales de Markdown.
- Carga Mermaid solo en las páginas que lo necesiten.
- Evita JavaScript global si la mayoría de las páginas no usan diagramas.
- Prueba los diagramas durante la vista previa local.
- Mantén el código fuente del diagrama legible en Git.
Para un blog técnico, los bloques de código delimitados suelen ser mejores que los shortcodes personalizados porque son más portátiles. Si luego mueves el contenido a GitHub, otro generador de sitios estáticos o una plataforma de documentación, los bloques Mermaid estándar delimitados son más fáciles de reutilizar.
Mejores Prácticas de Mermaid
Mantén los Diagramas Pequeños
Un diagrama debe aclarar el artículo, no reemplazarlo. Si los lectores necesitan hacer zoom, el diagrama probablemente es demasiado grande.
Los buenos diagramas suelen tener:
- Una idea
- Dirección clara
- Etiquetas cortas
- Pocas líneas cruzadas
- Nomenclatura consistente
Prefiere Múltiples Diagramas Pequeños
En lugar de un diagrama de sistema enorme, usa varios diagramas enfocados:
- Flujo de solicitud
- Topología de despliegue
- Modelo de datos
- Ciclo de vida del estado
- Ruta de falla
Esto es mejor para los lectores y mejor para pantallas móviles.
Usa Nombres Estables
Usa nombres que coincidan con tu código, API o documentación. No llames a lo mismo API, Backend y Servidor en diferentes diagramas a menos que esos sean verdaderamente conceptos diferentes.
Etiqueta las Flechas Importantes
Las flechas sin etiqueta están bien para diagramas de flujo simples. En diagramas de sistema, las etiquetas a menudo importan.
este código:
```mermaid
flowchart LR
Web -->|Solicitud HTTPS| API
API -->|Consulta SQL| DB
API -->|Publicar evento| Cola
```
Produce este diagrama:
Evita Sintaxis Ingeniosa
Mermaid puede hacer muchas cosas. Eso no significa que cada artículo necesite usarlas todas. Favorece la sintaxis que un futuro mantenedor pueda entender rápidamente.
Usa Comillas en Etiquetas Cuando Sea Necesario
Si una etiqueta contiene caracteres que confunden a Mermaid, envuélvela en comillas.
este código:
```mermaid
flowchart TD
A["El usuario hace clic en /checkout"] --> B["POST /api/orders"]
```
Produce este diagrama:
Este es un pequeño hábito que previene frustrantes fallos de renderizado.
Piensa en el Modo Oscuro
Muchos sitios de Hugo soportan el modo oscuro. Asegúrate de que tu tema de Mermaid o CSS del sitio mantenga los diagramas legibles tanto en apariencia clara como oscura.
Errores Comunes de Mermaid
Error 1: Demasiado Detalle
Los malos diagramas de Mermaid a menudo intentan mostrar cada caso extremo. Eso los hace técnicamente completos pero prácticamente ilegibles. La corrección casi siempre es la misma: dividir el diagrama en dos o tres más pequeños, cada uno cubriendo una preocupación, para que los lectores puedan seguir la lógica sin tener que rastrear una docena de flechas cruzadas.
Error 2: Etiquetas Largos
Las etiquetas largas crean cajas anchas y diseños feos.
En lugar de este código:
```mermaid
flowchart TD
A[El usuario envía el formulario de registro con su dirección de correo electrónico y contraseña]
```
Produce este diagrama:
Prefiere este código:
```mermaid
flowchart TD
A[Enviar formulario de registro]
```
Produce este diagrama:
Explica los detalles en el párrafo debajo del diagrama.
Error 3: Dirección Poco Clara
Elige una dirección y cúmplela. La mayoría de los diagramas de proceso deberían usar TD. La mayoría de los diagramas de arquitectura son más fáciles con LR.
Error 4: Tratar Mermaid como una Herramienta de Diseño
Mermaid no es Figma. No está diseñado para diagramas perfectos en píxeles, y tratar de obligarlo a ese rol solo llevará a la frustración. Su fortaleza es la mantenibilidad, no la perfección visual — y ese compromiso es intencional.
Consejos de SEO de Mermaid para Blogs Técnicos
Los diagramas de Mermaid pueden hacer que los artículos técnicos sean más útiles, pero los motores de búsqueda aún necesitan texto. No confíes solo en los diagramas.
Para artículos de Mermaid amigables con el SEO:
- Usa títulos descriptivos H2 y H3.
- Explica cada diagrama en el texto cercano.
- Incluye las palabras clave importantes en el prosa normal.
- Mantén los ejemplos de código copiadores.
- Agrega una explicación estilo “alt” debajo de diagramas complejos.
- Usa título y descripción concisos en el front matter.
- Evita ocultar todo el significado dentro del SVG renderizado.
Un diagrama de Mermaid debe apoyar al artículo. No debería ser el único lugar donde exista información importante.
Ejemplos de Mermaid para Copiar y Pegar
Flujo de Solicitud de API
este código:
```mermaid
sequenceDiagram
participant Cliente
participant API
participant Autenticación
participant BaseDeDatos
Cliente->>API: GET /account
API->>Autenticación: Validar token
Autenticación-->>API: Token válido
API->>BaseDeDatos: Cargar cuenta
BaseDeDatos-->>API: Datos de la cuenta
API-->>Cliente: 200 OK
```
Produce este diagrama:
Pipeline de CI
este código:
```mermaid
flowchart TD
A[Empujar commit] --> B[Instalar dependencias]
B --> C[Ejecutar lint]
C --> D[Ejecutar pruebas]
D --> E[Compilar sitio]
E --> F[Desplegar]
```
Produce este diagrama:
Este patrón mapea naturalmente a una configuración de CI real. Para la sintaxis paso a paso de flujos de trabajo de GitHub Actions, la Hoja de Referencia de GitHub Actions es un compañero útil cuando quieres convertir el diagrama anterior en un pipeline funcional.
Flujo de Trabajo de Publicación
este código:
```mermaid
stateDiagram-v2
[*] --> Borrador
Borrador --> Edición
Edición --> Revisión
Revisión --> Publicado
Revisión --> Edición
Publicado --> [*]
```
Produce este diagrama:
Modelo de Datos Simple
este código:
```mermaid
erDiagram
AUTOR ||--o{ POST : escribe
POST ||--o{ COMENTARIO : recibe
AUTOR {
string id
string nombre
}
POST {
string id
string título
datetime publicado_en
}
COMENTARIO {
string id
string cuerpo
}
```
Produce este diagrama:
Cuándo No Usar Mermaid
No uses Mermaid cuando:
- El diagrama necesite un diseño visual preciso.
- El diseño deba coincidir exactamente con un sistema de marca.
- El visual sea mayoritariamente decorativo.
- El diagrama tenga demasiados nodos para leer.
- Una captura de pantalla explicaría mejor el punto.
- El contenido cambia raramente y necesita más pulido que mantenibilidad.
Mermaid es excelente para documentación técnica viva. Es menos bueno para arte de grado de presentación. Para diagramas de calidad de documento en contextos de impresión o PDF, LaTeX ofrece paquetes como TikZ y pgfplots que te dan un control de diseño mucho mayor — la Hoja de Referencia de LaTeX cubre la inclusión de diagramas junto con el resto de la caja de herramientas de LaTeX.
Pensamientos Finales
Mermaid es una de las mejores herramientas para blogs técnicos porque respeta cómo los desarrolladores ya trabajan: archivos de texto, Markdown, Git, revisión de código y compilaciones repetibles. Para todo lo que rodea a los diagramas — títulos, listas, tablas, bloques de código — la Hoja de Referencia de Markdown es el compañero de referencia rápida para mantener junto con esta guía.
Los mejores diagramas de Mermaid no son los más complejos. Son los diagramas que hacen que un concepto sea obvio y permanecen fáciles de editar seis meses después.
Usa Mermaid para los diagramas que deberían vivir con tu documentación. Manténlos pequeños, mantenlos legibles y trátalos como parte del código fuente de tu artículo.
