Guía completa de diagramas Mermaid.js
Aprende a crear diagramas profesionales con una sintaxis sencilla basada en texto
¿Qué es Mermaid.js?
Mermaid es una herramienta de diagramación y gráficos basada en JavaScript que utiliza definiciones de texto inspiradas en Markdown para crear y modificar diagramas dinámicamente. Es un proyecto de código abierto que permite generar diagramas a partir de descripciones de texto simples.
En lugar de usar herramientas de dibujo complejas, escribes una sintaxis similar a código que describe tu diagrama, y Mermaid lo renderiza como un diagrama visual. Este enfoque hace que los diagramas sean versionables, fáciles de actualizar y perfectos para la documentación.
Mermaid se integra perfectamente con plataformas de documentación, wikis y archivos Markdown, lo que la convierte en una herramienta favorita entre desarrolladores y redactores técnicos.
¿Por qué usar Mermaid.js?
- Control de versiones: los diagramas son archivos de texto, por lo que se pueden rastrear en Git junto con tu código
- Actualizaciones rápidas: cambia unas pocas líneas de texto en lugar de redibujar diagramas completos
- Consistencia: Mermaid maneja automáticamente el diseño y el estilo, garantizando diagramas consistentes
- Sin herramientas de diseño: no necesitas Visio, Lucidchart ni otras herramientas costosas
- Documentación como código: mantén los diagramas en el mismo repositorio que tu documentación
- Multiplataforma: funciona en navegadores y Node.js, e integra con muchas plataformas
- Gratis y de código abierto: sin costos de licencia, comunidad activa
- Múltiples tipos de diagramas: admite diagramas de flujo, de secuencia, de clases y más
Tipos de diagramas compatibles
Mermaid admite una amplia variedad de tipos de diagramas para cubrir distintas necesidades de documentación:
Diagrama de flujo
Visualiza flujos de trabajo, procesos y árboles de decisión con nodos y aristas.
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Process]
B -->|No| D[Alternative]
C --> E[End]
D --> ECaso de uso: Flujos de procesos, algoritmos, lógica de decisiones
Diagrama de secuencia
Muestra interacciones entre distintos actores o sistemas a lo largo del tiempo.
sequenceDiagram
participant User
participant API
participant DB
User->>API: Request data
API->>DB: Query
DB-->>API: Results
API-->>User: ResponseCaso de uso: Interacciones de API, comunicación de sistemas, flujos de usuarios
Diagrama de clases
Modela sistemas orientados a objetos con clases, atributos y relaciones.
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+bark()
}
Animal <|-- DogCaso de uso: Arquitectura de software, diseño OOP, esquemas de base de datos
Diagrama de estados
Representa estados y transiciones en un sistema o proceso.
stateDiagram-v2
[*] --> Idle
Idle --> Loading: Start
Loading --> Success: Complete
Loading --> Error: Fail
Success --> [*]
Error --> Idle: RetryCaso de uso: Máquinas de estado, gestión del ciclo de vida, estados de UI
Diagrama entidad‑relación
Modela estructuras de bases de datos y relaciones entre entidades.
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
CUSTOMER {
int id
string name
string email
}Caso de uso: Diseño de bases de datos, modelado de datos, arquitectura de sistemas
Diagrama de Gantt
Planifica y visualiza cronogramas y líneas de tiempo de proyectos.
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Design :a1, 2024-01-01, 30d
Development :a2, after a1, 45dCaso de uso: Planificación de proyectos, cronogramas de sprint, roadmaps
Gráfico circular
Muestra datos proporcionales y porcentajes de forma visual.
pie title Distribution
"Category A" : 42
"Category B" : 30
"Category C" : 28Caso de uso: Resultados de encuestas, cuota de mercado, asignación de recursos
Gráfico de Git
Visualiza estrategias de ramificación de Git y el historial de commits.
gitGraph
commit
branch develop
checkout develop
commit
checkout main
merge developCaso de uso: Documentación de flujos de trabajo de Git, estrategias de branching
Primeros pasos con Mermaid
1. Elige tu tipo de diagrama
Empieza decidiendo qué tipo de diagrama representa mejor lo que quieres mostrar. Cada tipo comienza con una palabra clave específica como 'flowchart', 'sequenceDiagram' o 'classDiagram'.
2. Escribe la sintaxis de texto
Usa la sintaxis sencilla de Mermaid para describir tu diagrama. La sintaxis es intuitiva y se lee casi como lenguaje natural. Por ejemplo, 'A --> B' crea una flecha de A a B.
3. Previsualiza tu diagrama
Usa nuestro visor en línea o cualquier herramienta compatible con Mermaid para ver tu diagrama renderizado en tiempo real. Ajusta lo necesario hasta quedar satisfecho.
4. Exporta y comparte
Exporta tu diagrama como SVG o PNG para presentaciones, o comparte una URL con tu equipo. También puedes incrustar Mermaid directamente en archivos Markdown.
Buenas prácticas
- Mantén los diagramas centrados en un solo concepto o flujo de trabajo
- Usa etiquetas significativas que describan la lógica de negocio real
- Divide diagramas complejos en diagramas más pequeños e interconectados
- Añade comentarios con %% para explicar secciones complejas
- Utiliza convenciones de nombres consistentes en tus diagramas
- Prueba tus diagramas en el entorno objetivo antes de finalizarlos
- Incluye indicaciones de dirección (TD, LR) para controlar el diseño cuando sea necesario
- Usa subgraphs para agrupar nodos relacionados en diagramas de flujo
- Aprovecha las opciones de estilo con moderación para mantener la legibilidad
- Controla versiones de los archivos fuente de tus diagramas junto con tu código
Casos de uso comunes
Documentación de software
Documenta arquitectura de sistemas, flujos de API e interacciones de componentes junto con tu código.
Planificación de proyectos
Crea diagramas de Gantt para planificación de sprints, cronogramas de proyectos y asignación de recursos.
Propuestas técnicas
Visualiza soluciones propuestas, diseños de sistemas y decisiones de arquitectura.
Recorridos de usuario
Mapea flujos de usuario, experiencias de cliente y patrones de interacción.
Diseño de bases de datos
Modela relaciones entre entidades, estructuras de esquema y dependencias de datos.
Documentación de procesos
Documenta procesos de negocio, flujos de trabajo y procedimientos operativos estándar.
Materiales educativos
Crea diagramas claros y versionados para tutoriales y cursos técnicos.
Documentación de API
Ilustra flujos de solicitud/respuesta, secuencias de autenticación e interacciones de endpoints.
Recursos adicionales
Preguntas frecuentes
Preguntas comunes sobre el uso de Mermaid Viewer y la creación de diagramas
¿Listo para crear tu primer diagrama?
Prueba nuestro visor gratuito de Mermaid en línea y empieza a crear diagramas profesionales en minutos.
Abrir el visor de Mermaid