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 - 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/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