Sintaxis de Diagramas Mermaid: Ejemplos para Markdown y Obsidian

Un diagrama Mermaid es una representación visual generada a partir de código en texto plano utilizando la biblioteca Mermaid JS. Creado por Knut Sveidqvist alrededor de 2014, este proyecto de código abierto Mermaid ha crecido hasta convertirse en el estándar para diagramas basados en texto en la documentación de software. En 2026, las principales plataformas, incluidas GitHub, GitLab y herramientas de documentación, renderizan la sintaxis Mermaid de forma nativa.

Esta guía explica la sintaxis de Mermaid, los tipos de diagramas principales, el renderizado en Markdown y Obsidian, las opciones de exportación y los puntos de fallo comunes.

Así se ve la sintaxis básica:

graph TD
    A[Start] --> B[Process]
    B --> C[Complete]

El enfoque de “diagramas como código” mejora la mantenibilidad mediante el control de versiones y simplifica la colaboración entre los equipos de ingeniería. Las secciones posteriores cubren los tipos de diagramas comunes, la creación paso a paso y cómo exportar diagramas para las partes interesadas que prefieren imágenes estáticas.

Hoja de accesos rápidos de sintaxis Mermaid

Diagrama	Palabra clave de apertura	Uso típico
Diagrama de flujo	flowchart TD o flowchart LR	Procesos y decisiones
Secuencia	sequenceDiagram	Solicitudes, respuestas e interacciones de servicios
Entidad-Relación	erDiagram	Entidades y relaciones de bases de datos
Estado	stateDiagram-v2	Cambios de estado y ciclo de vida
Gantt	gantt	Hitos y cronogramas
Clase	classDiagram	Modelos de dominio y objetos

Cada bloque de Mermaid necesita una palabra clave de apertura de diagrama. Los ID de nodo deben mantenerse cortos y estables; las etiquetas visibles pueden contener texto más largo legible por humanos.

¿Qué es un diagrama Mermaid y por qué deberías usar uno?

Un diagrama Mermaid se genera a partir de una sintaxis de texto liviana interpretada por la biblioteca JavaScript Mermaid. En lugar de usar una interfaz de arrastrar y soltar, escribes código de diagrama Mermaid que la biblioteca convierte en gráficos SVG.

Cómo el código Mermaid se convierte en gráficos:

• graph TD; A –> B; se renderiza como un diagrama de flujo de arriba hacia abajo

• los bloques sequenceDiagram se convierten en diagramas de secuencia que muestran flujos de mensajes

• las definiciones erDiagram producen diagramas de entidad-relación

Beneficios clave de los diagramas mediante texto:

• Texto plano legible por humanos que cualquiera puede editar

• Diffs amigables con Git que muestran exactamente qué cambió

• Revisiones de código más sencillas en solicitudes de extracción (pull requests)

• Sin archivos de diagrama propietarios que gestionar

Casos de uso concretos para 2026:

• Documentar un flujo de autenticación de microservicios con diagramas de secuencia

• Mapear pipelines de CI/CD desde el commit hasta el despliegue en producción

• Planificar los hitos de lanzamiento de productos para el Q2 2026 con diagramas Gantt

Los diagramas Mermaid se integran de forma natural con la documentación basada en Markdown, wikis internas y portales para desarrolladores, simplificando los procesos de documentación en toda tu organización.

Tipos de diagramas Mermaid principales

Mermaid admite una amplia gama de tipos de gráficos. Esta sección proporciona una visión práctica de los más útiles en lugar de una referencia exhaustiva.

Tipos de diagramas principales:

Tipo	Palabra clave	Ideal para
Diagramas de flujo	graph TD / flowchart LR	Flujos de procesos, árboles de decisión
Diagramas de secuencia	sequenceDiagram	Llamadas a API, interacciones de servicios
Diagramas de clases	classDiagram	Modelos de objetos, diseño de dominio
Diagramas de estado	stateDiagram-v2	Estados del ciclo de vida, flujos de trabajo
Diagramas entidad-relación	erDiagram	Diseño de esquemas de bases de datos
Recorrido del usuario	journey	Mapeo de la experiencia del cliente
Diagramas Gantt	gantt	Cronogramas de proyectos, hojas de ruta
Gráficos circulares	pie	Visualización de datos proporcionales
Gráficos Git	gitGraph	Estrategias de ramificación

Ejemplos del mundo real:

• Diagramas de secuencia para flujos de Frontend → API Gateway → Payment Service API

• Diagramas Gantt para tu hoja de ruta de características del Q2 2026 con dependencias

• Diagramas de estado para el ciclo de vida del pedido: Pendiente → Pagado → Enviado → Entregado

Los diagramas de flujo, diagramas de secuencia, diagramas ER y diagramas de estado son los más comunes para los equipos de software. Los equipos de producto y operaciones suelen inclinarse hacia recorridos de usuario, Gantt y gráficos circulares para procesos de clientes y negocios.

sequenceDiagram
    participant User
    participant API
    User->>API: POST /login
    API-->>User: 200 OK + Token

Cómo crear diagramas Mermaid

Crear diagramas de flujo rápidamente comienza por comprender la estructura básica. Puedes crear diagramas utilizando cualquier editor de texto y sintaxis Mermaid.

Proceso paso a paso:

1. Comienza con una palabra clave de diagrama (graph TD, sequenceDiagram, gantt)

2. Define nodos o participantes con ID y etiquetas

3. Conecta elementos con flechas o relaciones

4. Agrega etiquetas y agrupaciones según sea necesario

Aquí tienes un diagrama de flujo de proceso de inicio de sesión completamente funcional:

graph TD
    U[User] --> LP[Login Page]
    LP --> AS[Auth Service]
    AS --> DB[(User Database)]
    AS -->|Success| DASH[Dashboard]
    AS -->|Failure| ERR[Error Page]

Tipos de flechas y etiquetas:

• –> crea una flecha dirigida estándar

• –>|label| agrega texto condicional a los conectores

• — dibuja una línea sin punta de flecha

• -.-> produce una flecha punteada para relaciones indirectas

Mermaid distribuye automáticamente los nodos utilizando algoritmos de diseño ELK. Concéntrate en la estructura lógica y la sintaxis en lugar del posicionamiento manual; no es necesario escribir código adicional para la ubicación.

Dónde puedes usar diagramas Mermaid en 2026

Muchas plataformas principales ahora admiten Mermaid de forma nativa o mediante extensiones, lo que facilita comenzar a crear diagramas de inmediato.

Entornos clave:

• GitHub y GitLab: Renderizado nativo en README.md, documentación, issues y wikis

• Generadores de sitios estáticos: Docusaurus, MkDocs y Sphinx con extensiones

• Portales de desarrolladores internos: Backstage y aplicaciones React personalizadas

• Herramientas de toma de notas: Notion y Obsidian con soporte integrado para gráficos Mermaid

Visual Studio Code y los IDE de JetBrains admiten la vista previa en vivo a través de extensiones, lo que te permite visualizar los diagramas a medida que escribes. Esto ayuda a detectar un error de sintaxis antes de confirmar los cambios.

Algunas plataformas como Confluence Cloud requieren complementos del mercado. Los equipos a menudo almacenan diagramas externamente en repositorios de código mientras mantienen las imágenes exportadas al lado para una mayor visibilidad.

Renderizado de diagramas Mermaid en diferentes plataformas

El renderizado transforma el texto de Mermaid en imágenes SVG/HTML visuales. El método depende de cómo funcione el gráfico Mermaid con tu plataforma receptora.

El patrón general: coloca el código Mermaid en bloques de código delimitados con el identificador de lenguaje mermaid. GitHub, GitLab y los generadores de documentación renderizan automáticamente estos bloques cuando se ven en navegadores.

Para el desarrollo local, las extensiones o complementos proporcionan vista previa en vivo. En la documentación basada en Sphinx, habilita el renderizado a través de extensiones como sphinxcontrib-mermaid que procesan diagramas generados durante la compilación.

Renderizar Mermaid en archivos Markdown

Para renderizar Mermaid en Markdown:

1. Usa tres comillas invertidas (backticks) para abrir un bloque de código

2. Especifica mermaid como el identificador del lenguaje

3. Agrega tu definición de diagrama dentro

4. Cierra con tres comillas invertidas

```mermaid
flowchart LR
    A[Step 1] -->|Process| B[Step 2]
    B -->|Complete| C[Step 3]
```

• GitHub, GitLab y los sitios de documentación modernos admiten este patrón directamente

• Prueba el renderizado en un entorno de vista previa antes de fusionar a producción

• El tema predeterminado del gráfico Mermaid funciona bien para la mayoría de la documentación

Renderizar Mermaid en Obsidian

Obsidian renderiza Mermaid desde un bloque de código mermaid delimitado en la Vista de lectura y en la Vista previa en vivo. El soporte de Mermaid está integrado, por lo que no necesitas un complemento de la comunidad para un diagrama básico.

Si un diagrama no se renderiza:

1. Confirma que el bloque de apertura sea exactamente ```mermaid.
2. Verifica la primera línea para obtener una palabra clave de diagrama válida como flowchart LR.
3. Reemplaza las etiquetas con mucha puntuación por etiquetas entre comillas, por ejemplo A["Review: blocked?"].
4. Reduce el ejemplo a dos nodos y luego vuelve a agregar líneas hasta que aparezca la sintaxis que falla.
5. Comprueba si la versión instalada de Obsidian admite cualquier sintaxis Mermaid más nueva que hayas copiado.

Para otras extensiones de Markdown específicas de Obsidian, consulta la hoja de accesos rápidos de formato para Obsidian.

Renderizar Mermaid en IDE y herramientas locales

El complemento de Visual Studio Code para Mermaid permite la vista previa en vivo lado a lado a medida que editas diagramas. Varias extensiones proporcionan resaltado de sintaxis y sugerencias de reparación de diagramas para diagramas complejos.

Los IDE de JetBrains ofrecen capacidades similares a través de complementos, que a menudo incluyen pistas de errores y opciones de exportación. Un botón para reparar diagramas en algunas herramientas puede solucionar automáticamente problemas comunes de sintaxis.

Las vistas previas locales ayudan a detectar errores antes de enviarlos a los repositorios de Git. Estandariza un conjunto de extensiones recomendado en tu documentación de configuración de desarrollador.

Exportación y uso compartido de diagramas Mermaid

Si bien las opciones de edición basadas en código funcionan para los desarrolladores, las partes interesadas a menudo prefieren imágenes estáticas para presentaciones de Microsoft PowerPoint e informes.

Formatos de exportación comunes:

• PNG: Compartir rápidamente a través de herramientas de mensajería

• SVG: Gráficos escalables de alta calidad para diapositivas

• PDF: Paquetes de documentación imprimibles

Los flujos de trabajo de exportación varían según la herramienta. Algunas incluyen un botón de exportación integrado, mientras que otras requieren el editor de gráficos Mermaid o herramientas en línea como Mermaid Live Editor. Las herramientas de línea de comandos pueden generar imágenes por lotes a partir de múltiples archivos de diagrama como parte de CI/CD, una forma de automatización impulsada por código.

Mantén siempre la fuente Mermaid original junto con los recursos exportados para que los diagramas sigan siendo editables.

Convertir diagramas Mermaid a formatos de imagen

Mini flujo de trabajo utilizando un editor en línea:

1. Abre Mermaid Live Editor en tu navegador

2. Pega tu código Mermaid o usa diagramas de muestra como plantillas

3. Ajusta la configuración de estilo del gráfico Mermaid

4. Configura múltiples temas si es necesario (opciones de modo oscuro y claro disponibles)

5. Haz clic en “Descargar SVG” o “Descargar PNG”

Asegúrate de que los diagramas exportados utilicen fuentes y colores consistentes alineados con las pautas de la marca. Las capturas de pantalla de GitHub se rasterizarán y es posible que no se escalen bien; usa exportaciones SVG para presentaciones de diapositivas siempre que sea posible.

Mejores prácticas y limitaciones de los diagramas Mermaid

Mermaid es potente, pero funciona mejor con un alcance y una estructura bien meditados para las tareas de diagramación.

Recomendaciones:

• Limita cada diagrama a un solo concepto enfocado

• Usa etiquetas de nodo descriptivas y patrones de nombres consistentes

• Agrupa los pasos relacionados con bloques subgráficos

• Mantén los diagramas complejos como archivos separados en lugar de una suite de diagramación visual masiva

Limitaciones a considerar:

• Los sistemas grandes y densos se vuelven difíciles de gestionar como código

• El control del diseño es aproximado: sin posicionamiento de píxel perfecto

• El estilo es menos flexible que en las herramientas de diagramación tradicionales o una suite de diagramación en pizarra

• No es ideal para diagramación basada en imágenes conceptuales o maquetas de IU

Usa Mermaid para descripciones generales de arquitectura y flujos de trabajo. Cambia a herramientas especializadas cuando se requieran diseños de píxel perfecto o topologías de red complejas. Es posible que aún se necesite un editor visual de diagramas para ciertos casos de uso.

Guía rápida para comenzar con los diagramas Mermaid

Lista de verificación de acciones para nuevos usuarios:

1. Elige un tipo de diagrama (generalmente diagrama de flujo para crear diagramas de flujo fácilmente)

2. Instala una extensión habilitada para editor visual o chat de IA o abre Mermaid Live Editor

3. Dibuja un proceso real de tu proyecto actual: tu pipeline de despliegue de 2026 funciona bien

4. Reitera y expande a medida que aprendes patrones de sintaxis de código

Recursos clave:

• Documentación oficial de Mermaid para obtener una referencia completa de la sintaxis

• Mermaid Live Editor para experimentar con funciones integradas de generación de IA

• Extensiones de VS Code con fragmentos de código y plantillas

• Considera una cuenta básica en plataformas de colaboración para obtener funciones de equipo

Agrega una sección “Directrices de diagramas” a tu manual de ingeniería que cubra las convenciones de nomenclatura, los tipos de diagramas preferidos y los permisos de diagramas. Algunos equipos encuentran que las descripciones en lenguaje natural combinadas con herramientas de chat de IA integradas aceleran la creación de diagramas para cualquier nivel de habilidad técnica.

La adopción de diagramas Mermaid alinea tu documentación con las mismas prácticas de revisión y automatización utilizadas para el código fuente. Ya seas un ingeniero de aprendizaje automático que documenta pipelines de modelos o el propietario de un kit de herramientas de gestión de proyectos que mapea flujos de trabajo, Mermaid aporta elementos visuales controlados por versiones a tu equipo. Comienza con un diagrama hoy mismo.