Diagramas de Mermaid Arquitectura del documento en Markdown sin hacer clic en nada

Tu diagrama de arquitectura era preciso cuando lo dibujaste. Eso fue hace tres iteraciones. Ahora está en un Google Slide compartido que nadie actualiza, y el ingeniero que construyó el servicio que describe ya cambió de equipo. ¿Se parece a esto?

Los diagramas de Mermaid invierten este problema. En lugar de tener un lienzo de arrastrar y soltar que vive fuera de tu código, escribes los diagramas como texto — una sintaxis en estilo Markdown plano que se encuentra en tu README, se controla con el código y se renderiza en cualquier lugar donde se renderice Markdown. Cuando cambia la arquitectura, cambias un archivo de texto. La diferencia muestra toda la historia.

Qué es Mermaid (y por qué los diagramas como código importan)

Mermaid es un lenguaje abierto de diagramación que renderiza diagramas a partir de texto plano. Escribe un diagrama de flujo en un bloque de código; un renderizador (o un visor que entienda Mermaid) lo convierte en un diagrama SVG. No necesitas cuentas, no hay pasos de exportación, no hay «el formato de diagrama no está soportado en esta máquina».

El enfoque de «diagramas como código» se justifica de varias maneras concretas:

• Control de versiones — los diagramas viven en Git. Puedes compararlos, revertirlos y adjuntarlos a la misma solicitud de código que describen.
• Sin dependencia de proveedor — el texto plano es portátil. Puedes cambiar el renderizador, forkar el repositorio, exportar a Confluence — el origen siempre es legible.
• Cerca del código siempre — un diagrama en el mismo repositorio que el servicio que describe es mucho más probable que permanezca preciso que uno en un deck compartido.
• Amigable para automatización — puedes generar sintaxis de Mermaid a partir del código (esquemas de base de datos, especificaciones de API, pipelines de CI) usando scripts o modelos de lenguaje.

Antes de profundizar en los tipos de diagramas, puedes ver cualquier sintaxis de Mermaid de forma inmediata — sin necesidad de configuración local — usando el Renderizador de Diagramas de Mermaid en iotools.cloud. Pega, ve el resultado, itera. Usa esto junto con esta guía para ejecutar cada ejemplo en tiempo real.

Flujo de procesos: El trabajo diario

Los diagramas de flujo son el tipo más común de diagrama de Mermaid, y por una buena razón — manejan desde árboles de decisión simples hasta flujos complejos de múltiples servicios. Aquí está la sintaxis que cubre 90% de casos reales:

flowchart TD
    A[User submits form] --> B{Validation passes?}
    B -- Yes --> C[Save to database]
    B -- No --> D[Return error to client]
    C --> E[Send confirmation email]
    E --> F([End])

Algunas cosas importantes sobre la sintaxis de diagramas de flujo:

• Dirección: TD (de arriba hacia abajo), LR (de izquierda a derecha), BT (de abajo hacia arriba), RL (de derecha a izquierda)
• Formas de nodos: [rectangle], (rounded), ([stadium]), {diamond}, ((circle)), [(cylinder)]
• Etiquetas de aristas: -- label --> o -->|label|
• Subgrupos: agrupa visualmente nodos relacionados

Los subgrupos son especialmente útiles para mostrar límites de servicios:

flowchart LR
    subgraph Frontend
        UI[React App]
    end
    subgraph Backend
        API[FastAPI]
        DB[(PostgreSQL)]
    end
    UI --> API
    API --> DB

Diagramas de secuencia: Mostrar flujos de llamadas de API

Los diagramas de secuencia son la herramienta adecuada cuando necesitas mostrar el orden de interacciones entre sistemas — una cadena de llamadas de API, un flujo de autenticación, una secuencia de webhook. Hacen clara la secuencia y la responsabilidad de una forma que un diagrama de flujo no puede.

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Users DB

    Client->>API Gateway: POST /login {email, password}
    API Gateway->>Auth Service: Validate credentials
    Auth Service->>Users DB: SELECT user WHERE email=?
    Users DB-->>Auth Service: User record
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK {token}

Flechas sólidas (->>) son solicitudes; flechas discontinuas (-->>) son respuestas. Las participant declaraciones controlan el orden en que aparecen los cuadros al inicio del diagrama. También puedes usar actor para participantes humanos, activate/deactivate para mostrar el tiempo de procesamiento, y loop o alt bloques para flujos condicionales.

Diagramas de entidad-relación: Esquemas de bases de datos en la documentación

Los diagramas de entidad-relación deben incluirse en cada README de un servicio que tenga un esquema de base de datos. La sintaxis de ER de Mermaid es limpia y cubre la cardinalidad de forma nativa:

erDiagram
    USER {
        int id PK
        string email
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

Notación de cardinalidad: || es exactamente uno, o| es cero o uno, o{ es cero o muchos, |{ es uno o muchos. La etiqueta de la relación (“places”, “contains”) va entre comillas al final.

Diagramas de estado: Modelar flujos y máquinas de estado

Cualquier vez que tengas un ente que cambie de estado — un pedido, una suscripción, una tarea de CI — un diagrama de estado es más preciso que un diagrama de flujo. La sintaxis de diagrama de estado de Mermaid se alinea directamente con cómo definirías una máquina de estado en el código:

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing : payment received
    Processing --> Shipped : warehouse picks order
    Shipped --> Delivered : carrier confirms
    Shipped --> Returned : customer initiates return
    Delivered --> [*]
    Returned --> Refunded : refund processed
    Refunded --> [*]

[*] marca los estados de inicio y final. Las transiciones llevan el evento que las activa. Puedes anidar estados para estados compuestos y usar note bloques para anotar transiciones con contexto adicional.

Diagramas de clases: Estructuras de OOP para guías de incorporación

Los diagramas de clases son más útiles cuando se incorporan ingenieros a un códigobase orientado a objetos o se documenta un modelo de dominio. Mermaid cubre herencia, interfaces, composición y firmas de métodos:

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +boolean isIndoor
        +purr() void
    }
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends

Los modificadores de visibilidad siguen la convención UML: + público, - privado, # protegido. Las flechas de relación cubren asociación (-->), herencia (<|--), composición (*--), y agregación (o--).

Donde Mermaid se renderiza nativamente

El punto fuerte real de Mermaid es su soporte nativo en las herramientas que ya usan los desarrolladores:

• GitHub — los bloques de código de Mermaid (```mermaid) se renderizan en READMEs, issues, descripciones de solicitudes de código y wikis desde 2022.
• GitLab — soporte nativo en archivos de Markdown y páginas de wiki.
• Notion — pega un bloque de código de Mermaid en un bloque de código configurado como "Mermaid" y se renderiza inline.
• (CLI) — la extensión de visualización de Markdown con soporte de Mermaid renderiza los diagramas en el panel de vista previa integrado.
• Obsidian — Mermaid se renderiza nativamente sin necesidad de plugin.
• Docusaurus, MkDocs, Astro — existen plugins de Mermaid para todos los generadores estáticos principales.
• Confluence — mediante la aplicación Mermaid Diagrams for Confluence.

Si estás escribiendo documentación que llegará a GitHub o GitLab, los diagramas de Mermaid funcionan directamente sin configuración.

Puntos débiles y cuándo usar algo diferente

Mermaid no es perfecto para todas las situaciones. Algunos aspectos a tener en cuenta:

• Diseños complejos — el algoritmo de diseño automático de Mermaid no siempre produce resultados limpios para gráficos grandes. Si tienes 50+ nodos con muchas aristas que se cruzan, podrías necesitar reestructurar o dividir manualmente los diagramas.
• Renderizado en Confluence — Confluence no tiene soporte nativo para Mermaid; necesitas una aplicación pagada. Si tu equipo vive en Confluence, debes presupuestar para esto o usar draw.io en su lugar.
• Tipos de diagramas no estándar — los diagramas de red, diagramas de despliegue y diagramas de arquitectura C4 requieren soluciones alternativas o no están bien soportados.
• Control de estilo — las opciones de theming de Mermaid son limitadas. Para diagramas con colores y fuentes personalizadas, tendrás que invertir tiempo luchando con el renderizador.

Las principales alternativas a conocer:

• PlantUML — sintaxis más antigua y más verbosa, pero mayor soporte UML y mejor integración con Confluence. Requiere Java local o un renderizador en servidor.
• D2 — herramienta más reciente de diagramas como código con mejor control de diseño y manejo de diagramas grandes. Menor adopción en el ecosistema que Mermaid, pero crece rápidamente.
• draw.io / Excalidraw — herramientas de interfaz gráfica para cuando necesitas control visual preciso y no te importa que el diagrama viva fuera del control de versiones.

Para la mayoría de las documentaciones de desarrolladores — READMEs de servicios, flujos de API, guías de incorporación — Mermaid cubre bien el caso y el soporte nativo en GitHub hace que sea merecedor de la curva de aprendizaje.

Vista previa de Mermaid sin instalar nada

Si estás experimentando con la sintaxis o quieres compartir un diagrama con alguien que no tenga un renderizador local instalado, el Renderizador de Diagramas de Mermaid en iotools.cloud te da una vista previa en tiempo real sin registro, sin instalación y sin configuración. Pega tu código de Mermaid, ve el diagrama renderizado y copia el resultado.

Es útil para verificar la sintaxis del diagrama antes de commit, compartir una versión renderizada en un mensaje de Slack o prototipar un diagrama que luego pegarás en un README.

Empieza con un diagrama de flujo

Si nunca has escrito un diagrama de Mermaid, empieza con un diagrama de flujo. Elige un proceso en tu códigobase que has estado queriendo documentar — el ciclo de solicitud, una tarea en segundo plano, un pipeline de despliegue — y escribe en Mermaid en los próximos 10 minutos. Pégalo en tu README dentro de un ```mermaid bloque y empuéalo. GitHub lo renderizará automáticamente.

Ese único diagrama, controlado por versiones y viviendo junto al código que describe, vale más que un deck compartido que nadie confía.

También te puede interesar