Mermaid Diagrams

Mermaid Diagramming

Create professional software diagrams using Mermaid’s text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code.

Core Syntax Structure

All Mermaid diagrams follow this pattern:

diagramType
  definition content

Key principles:

• First line declares diagram type (e.g., classDiagram, sequenceDiagram, flowchart)
• Use %% for comments
• Line breaks and indentation improve readability but aren’t required
• Unknown words break diagrams; parameters fail silently

Diagram Type Selection Guide

Choose the right diagram type:

• Class Diagrams – Domain modeling, OOP design, entity relationships
• Domain-driven design documentation
• Object-oriented class structures
• Entity relationships and dependencies

• Sequence Diagrams – Temporal interactions, message flows
• API request/response flows
• User authentication flows
• System component interactions
• Method call sequences

• Flowcharts – Processes, algorithms, decision trees
• User journeys and workflows
• Business processes
• Algorithm logic
• Deployment pipelines

• Entity Relationship Diagrams (ERD) – Database schemas
• Table relationships
• Data modeling
• Schema design

• C4 Diagrams – Software architecture at multiple levels
• System Context (systems and users)
• Container (applications, databases, services)
• Component (internal structure)
• Code (class/interface level)

• State Diagrams – State machines, lifecycle states
• Git Graphs – Version control branching strategies
• Gantt Charts – Project timelines, scheduling
• Pie/Bar Charts – Data visualization

Quick Start Examples

Class Diagram (Domain Model)

classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates
    
    class Title {
        +string name
        +int releaseYear
        +play()
    }
    
    class Genre {
        +string name
        +getTopTitles()
    }

Sequence Diagram (API Flow)

sequenceDiagram
    participant User
    participant API
    participant Database
    
    User->>API: POST /login
    API->>Database: Query credentials
    Database-->>API: Return user data
    alt Valid credentials
        API-->>User: 200 OK + JWT token
    else Invalid credentials
        API-->>User: 401 Unauthorized
    end

Flowchart (User Journey)

flowchart TD
    Start([User visits site]) --> Auth{Authenticated?}
    Auth -->|No| Login[Show login page]
    Auth -->|Yes| Dashboard[Show dashboard]
    Login --> Creds[Enter credentials]
    Creds --> Validate{Valid?}
    Validate -->|Yes| Dashboard
    Validate -->|No| Error[Show error]
    Error --> Login

ERD (Database Schema)

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : includes
    
    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }
    
    ORDER {
        int id PK
        int user_id FK
        decimal total
        datetime created_at
    }

Detailed References

For in-depth guidance on specific diagram types, see:

• [references/class-diagrams.md](references/class-diagrams.md) – Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
• [references/sequence-diagrams.md](references/sequence-diagrams.md) – Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
• [references/flowcharts.md](references/flowcharts.md) – Node shapes, connections, decision logic, subgraphs, styling
• [references/erd-diagrams.md](references/erd-diagrams.md) – Entities, relationships, cardinality, keys, attributes
• [references/c4-diagrams.md](references/c4-diagrams.md) – System context, container, component diagrams, boundaries
• [references/advanced-features.md](references/advanced-features.md) – Themes, styling, configuration, layout options

Best Practices

• Start Simple – Begin with core entities/components, add details incrementally
• Use Meaningful Names – Clear labels make diagrams self-documenting
• Comment Extensively – Use %% comments to explain complex relationships
• Keep Focused – One diagram per concept; split large diagrams into multiple focused views
• Version Control – Store .mmd files alongside code for easy updates
• Add Context – Include titles and notes to explain diagram purpose
• Iterate – Refine diagrams as understanding evolves

Configuration and Theming

Configure diagrams using frontmatter:

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

Available themes: default, forest, dark, neutral, base

Layout options:

• layout: dagre (default) – Classic balanced layout
• layout: elk – Advanced layout for complex diagrams (requires integration)

Look options:

• look: classic – Traditional Mermaid style
• look: handDrawn – Sketch-like appearance

Exporting and Rendering

Native support in:

• GitHub/GitLab – Automatically renders in Markdown
• VS Code – With Markdown Mermaid extension
• Notion, Obsidian, Confluence – Built-in support

Export options:

• Mermaid Live Editor – Online editor with PNG/SVG export
• Mermaid CLI – npm install -g @mermaid-js/mermaid-cli then mmdc -i input.mmd -o output.png
• Docker – docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

Common Pitfalls

• Breaking characters – Avoid {} in comments, use proper escape sequences for special characters
• Syntax errors – Misspellings break diagrams; validate syntax in Mermaid Live
• Overcomplexity – Split complex diagrams into multiple focused views
• Missing relationships – Document all important connections between entities

When to Create Diagrams

Always diagram when:

• Starting new projects or features
• Documenting complex systems
• Explaining architecture decisions
• Designing database schemas
• Planning refactoring efforts
• Onboarding new team members

Use diagrams to:

• Align stakeholders on technical decisions
• Document domain models collaboratively
• Visualize data flows and system interactions
• Plan before coding
• Create living documentation that evolves with code