Guía completa de diagramas Mermaid

¿Qué es Mermaid?

¿Por qué usar Mermaid?

• 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:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[Alternative]
    C --> E[End]
    D --> E

sequenceDiagram
    participant User
    participant API
    participant DB
    User->>API: Request data
    API->>DB: Query
    DB-->>API: Results
    API-->>User: Response

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: Start
    Loading --> Success: Complete
    Loading --> Error: Fail
    Success --> [*]
    Error --> Idle: Retry

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    CUSTOMER {
        int id
        string name
        string email
    }

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Design :a1, 2024-01-01, 30d
    Development :a2, after a1, 45d

pie title Distribution
    "Category A" : 42
    "Category B" : 30
    "Category C" : 28

gitGraph
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop

Primeros pasos con Mermaid

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

Recursos adicionales

• Documentación oficial de Mermaid
• Repositorio de Mermaid en GitHub
• Referencia de sintaxis de Mermaid