Mermaid Cheat Sheet

Overview

Mermaid is a JavaScript-based diagramming and charting tool that renders text definitions into SVG diagrams and charts. It uses a Markdown-inspired syntax that makes it easy to create and modify diagrams as part of your documentation workflow. Mermaid is natively supported in GitHub, GitLab, Notion, Docusaurus, and many other platforms.

Mermaid supports flowcharts, sequence diagrams, class diagrams, state diagrams, entity relationship diagrams, Gantt charts, pie charts, git graphs, and more. Diagrams are defined in plain text, making them versionable with git and easy to include in Markdown documentation.

Installation

CLI

# Install globally
npm install -g @mermaid-js/mermaid-cli

# Generate SVG from a .mmd file
mmdc -i diagram.mmd -o diagram.svg

# Generate PNG
mmdc -i diagram.mmd -o diagram.png

# Generate PDF
mmdc -i diagram.mmd -o diagram.pdf

# With custom config
mmdc -i diagram.mmd -o diagram.svg -c mermaid-config.json

Browser / CDN

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true, theme: 'default' });
</script>

<pre class="mermaid">
  graph TD
    A-->B
</pre>

npm (for Bundlers)

npm install mermaid

import mermaid from 'mermaid';
mermaid.initialize({ startOnLoad: true });

Flowcharts

Node Shapes

Syntax	Shape
`A[Text]`	Rectangle
`A(Text)`	Rounded rectangle
`A([Text])`	Stadium / pill
`A[[Text]]`	Subroutine
`A[(Text)]`	Cylinder (database)
`A((Text))`	Circle
`A>Text]`	Asymmetric / flag
`A{Text}`	Diamond (decision)
`A{{Text}}`	Hexagon
`A[/Text/]`	Parallelogram
`A[\Text\]`	Parallelogram (alt)

Link Styles

Syntax	Style
`A --> B`	Arrow
`A --- B`	Line (no arrow)
`A -.- B`	Dotted line
`A -.-> B`	Dotted arrow
`A ==> B`	Thick arrow
`A -- text --> B`	Arrow with label
`A -. text .-> B`	Dotted with label
`A == text ==> B`	Thick with label
`A <--> B`	Bidirectional

Directions

Direction	Description
`graph TD`	Top to bottom
`graph TB`	Top to bottom
`graph BT`	Bottom to top
`graph LR`	Left to right
`graph RL`	Right to left

Subgraphs

graph TB
    subgraph Frontend
        A[React App] --> B[API Client]
    end
    subgraph Backend
        C[API Server] --> D[Database]
    end
    B --> C

Sequence Diagrams

sequenceDiagram
    participant U as User
    participant C as Client
    participant S as Server

    U->>C: Click Login
    C->>S: POST /auth/login
    activate S
    S-->>C: JWT Token
    deactivate S
    C->>U: Show dashboard

    alt Valid credentials
        S-->>C: 200 OK
    else Invalid credentials
        S-->>C: 401 Unauthorized
    end

    loop Health Check
        S->>S: Ping
    end

Arrow Types

Syntax	Description
`->>`	Solid line with arrowhead
`-->>`	Dotted line with arrowhead
`-x`	Solid line with cross
`--x`	Dotted line with cross
`-)`	Solid line with open arrow
`--)`	Dotted line with open arrow

Class Diagrams

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

Relationship Types

Syntax	Description
`<\|--`	Inheritance
`*--`	Composition
`o--`	Aggregation
`-->`	Association
`--`	Link (solid)
`..>`	Dependency
`..\|>`	Realization

State Diagrams

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : Submit
    Processing --> Success : Valid
    Processing --> Error : Invalid
    Error --> Idle : Retry
    Success --> [*]

    state Processing {
        [*] --> Validating
        Validating --> Saving
        Saving --> [*]
    }

Entity Relationship Diagrams

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"

    CUSTOMER {
        int id PK
        string name
        string email UK
    }
    ORDER {
        int id PK
        date created
        string status
    }

Gantt Charts

gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD

    section Planning
    Requirements    :done, req, 2024-01-01, 14d
    Design          :active, des, after req, 10d

    section Development
    Backend         :dev1, after des, 30d
    Frontend        :dev2, after des, 25d

    section Testing
    Integration     :test, after dev1, 10d

Pie Charts

pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 19
    "Firefox" : 4
    "Edge" : 4
    "Other" : 8

Git Graph

gitGraph
    commit
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout main
    merge feature
    commit

Configuration

{
  "theme": "default",
  "themeVariables": {
    "primaryColor": "#1a73e8",
    "primaryTextColor": "#ffffff",
    "lineColor": "#333333",
    "fontSize": "14px",
    "fontFamily": "Inter, sans-serif"
  },
  "flowchart": {
    "curve": "basis",
    "padding": 15
  },
  "sequence": {
    "diagramMarginX": 50,
    "actorMargin": 50,
    "mirrorActors": true
  }
}

Available Themes

Theme	Description
`default`	Standard light theme
`dark`	Dark background theme
`forest`	Green-toned theme
`neutral`	Grayscale theme
`base`	Customizable base theme

Troubleshooting

Issue	Solution
Diagram not rendering	Check syntax at mermaid.live; ensure mermaid.js is loaded
Special characters in labels	Wrap labels in quotes: `A["Label with (parens)"]`
Diagram too wide/tall	Reduce content or adjust config padding
GitHub not rendering	Use mermaid code fence in Markdown files
Font issues	Set `fontFamily` in theme variables
SVG export issues	Use CLI tool `mmdc` for reliable export
Complex diagram too slow	Simplify; break into smaller sub-diagrams
Theme colors not applying	Use init directive at top of diagram