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:

mermaid

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)

mermaid

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)

mermaid

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)

mermaid

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)

mermaid

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 - Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
•references/sequence-diagrams.md - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
•references/flowcharts.md - Node shapes, connections, decision logic, subgraphs, styling
•references/erd-diagrams.md - Entities, relationships, cardinality, keys, attributes
•references/c4-diagrams.md - System context, container, component diagrams, boundaries
•references/architecture-diagrams.md - Cloud services, infrastructure, CI/CD deployments
•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:

mermaid

---
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
•Orca Note, 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