Mermaid Cheatsheet — All 19 Diagram Types with Examples

What is Mermaid?

Mermaid is a text-to-diagram language. Write a few lines of plain text in a fenced code block and the renderer produces a flowchart, sequence diagram, ERD, Gantt chart, or one of 15 other diagram types. Because the source is text, AI assistants generate Mermaid reliably and the diagrams version-control like any other file.

Flowchart

A node-and-arrow graph for processes, decisions, and control flow. Supports four orientations (TD, LR, BT, RL) and shape syntax for rectangles, diamonds, circles, and stadiums.

process documentation
decision trees
algorithm explanations
system flowcharts

flowchart TD
    A[User] -->|Paste Mermaid code| B(MermanDraw)
    B --> C{Render}
    C -->|Beautiful| D[Diagram]
    C -->|Share| E[Link]
    E -->|Viral| A

Full guide →

Sequence Diagram

An interaction timeline between actors. Solid arrows mark synchronous calls, dashed arrows mark responses, with optional activation bars, notes, and parallel/alt blocks.

API request and response flows
auth handshakes
distributed system traces
protocol explanations

sequenceDiagram
    participant User
    participant Editor
    participant API
    participant DB
    User->>Editor: Paste Mermaid code
    Editor->>Editor: Render diagram (300ms debounce)
    User->>Editor: Click Share
    Editor->>API: POST /api/diagrams
    API->>DB: INSERT diagram
    DB-->>API: id
    API-->>Editor: { id }
    Editor-->>User: Share link copied!

Full guide →

User Journey

A user-experience map with sections and per-step satisfaction scores (1-5). Useful for visualising the emotional arc of a workflow rather than its branching logic.

UX walkthroughs
onboarding analysis
service blueprints
design reviews

journey
    title User creates a diagram
    section Discovery
      Find MermanDraw: 3: User
      Visit landing page: 4: User
    section Creating
      Open editor: 5: User
      Paste Mermaid code: 4: User
      See live preview: 5: User
      Adjust theme: 4: User
      Tweak layout: 3: User
    section Sharing
      Click Share: 5: User
      Copy link: 5: User
      Send to team: 5: User

Class Diagram

A UML class diagram with fields, methods, visibility modifiers, and relationships (inheritance, composition, association). Cardinalities are written as quoted labels on the connecting line.

object-oriented design
domain models
API surface documentation
refactoring discussions

classDiagram
    class Diagram {
        +String id
        +String code
        +String r2_key
        +Int view_count
        +save()
        +share() String
    }
    class User {
        +String id
        +String email
        +String plan
        +getDiagrams() Diagram[]
    }
    User "1" --> "many" Diagram : owns

Full guide →

Entity Relationship

An entity-relationship diagram for database schemas. Each entity lists typed columns with PK and FK markers; relationships use crow's-foot notation for cardinality.

database schema docs
data modelling
migration planning
review of ORM mappings

erDiagram
    USERS {
        text id PK
        text email
        text plan
        int created_at
    }
    DIAGRAMS {
        text id PK
        text code
        text r2_key
        int view_count
        int last_viewed_at
        text user_id FK
    }
    USERS ||--o{ DIAGRAMS : "owns"

Full guide →

Requirement

A SysML-style requirements diagram with typed requirements, risk levels, and verification methods. Trace, derive, and refine relationships connect requirements to each other and to their implementations.

compliance documentation
safety-critical specs
requirement traceability
audit artefacts

requirementDiagram
    requirement share_diagram {
        id: 1
        text: User can share a diagram via a unique URL
        risk: low
        verifymethod: test
    }
    functionalRequirement render_mermaid {
        id: 2
        text: Editor renders Mermaid diagrams in real time
        risk: medium
        verifymethod: demonstration
    }
    performanceRequirement fast_render {
        id: 3
        text: Diagram renders within 500ms of last keystroke
        risk: high
        verifymethod: test
    }
    share_diagram - refines -> render_mermaid
    fast_render - traces -> render_mermaid

Packet

A bit-level packet layout with labelled byte ranges. Renders network protocol headers, binary file formats, or any fixed-layout structure that benefits from a visual map.

network protocol docs
binary format specs
wire-format references
reverse-engineering notes

packet-beta
    title HTTP Request Packet
    0-7: "Version (4)"
    8-15: "IHL (5)"
    16-31: "Total Length"
    32-63: "Identification | Flags | Fragment Offset"
    64-71: "TTL"
    72-79: "Protocol (TCP=6)"
    80-95: "Header Checksum"
    96-127: "Source IP Address"
    128-159: "Destination IP Address"
    160-191: "Options (if IHL > 5)"

State Diagram

A state machine showing states, transitions, and events. Composite (nested) states, parallel regions, and entry/exit notation are supported via `stateDiagram-v2` syntax.

lifecycle modelling
workflow engines
protocol state machines
UI state transitions

stateDiagram-v2
    [*] --> Idle
    Idle --> Editing : user types
    Editing --> Rendering : debounce 300ms
    Rendering --> Rendered : success
    Rendering --> Error : parse fail
    Error --> Editing : user fixes
    Rendered --> Sharing : click Share
    Sharing --> Shared : API ok
    Shared --> [*]

Full guide →

Gantt

A project schedule with sections, dependencies via `after`, and statuses (`done`, `active`, `crit`). Dates use `dateFormat` to control parsing — `YYYY-MM-DD` is the safest default.

project plans
release roadmaps
sprint visualisation
dependency-aware scheduling

gantt
    title MermanDraw Roadmap
    dateFormat YYYY-MM-DD
    section Core
        Editor & Preview     :done,    e1, 2024-01-01, 14d
        PNG / SVG Export     :done,    e2, after e1, 7d
        Anonymous Sharing    :done,    e3, after e2, 7d
    section Launch
        Landing Page         :done,    l1, after e3, 5d
        Cloudflare Deploy    :done,    l2, after l1, 3d
    section Growth
        Google OAuth         :active,  g1, after l2, 14d
        Stripe / Pro Plan    :         g2, after g1, 14d
        AI Generation        :         g3, after g2, 21d

Full guide →

Timeline

A horizontal chronology grouped into sections, with multiple events per period. Lighter-weight than Gantt — no dependencies or durations, just dated milestones.

changelogs
project history
biographies and case studies
release notes

timeline
    title MermanDraw History
    section 2024 Q1
        Jan : Project started
            : Core editor built
        Feb : Mermaid rendering
            : 7 themes added
        Mar : Share feature
            : Cloudflare deploy
    section 2024 Q2
        Apr : Pan & Zoom
            : Local history
        May : Monokai Pro theme
            : Syntax highlight
        Jun : v1.0 public launch

Pie Chart

A simple pie chart with a title and labelled wedges. Values are absolute and Mermaid computes percentages — no need to normalise to 100 yourself.

proportion summaries
survey results
budget breakdowns
lightweight analytics

pie title MermanDraw Users by Type
    "AI Heavy Users" : 55
    "Developers" : 25
    "Designers" : 12
    "Others" : 8

Quadrant

A 2×2 prioritisation grid with named axes and quadrants. Plotted points use `[x, y]` coordinates between 0 and 1 — values map proportionally to the chart area.

feature prioritisation
risk-impact matrices
eisenhower box
competitive landscapes

quadrantChart
    title Feature Priority Matrix
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Quick wins
    quadrant-2 Major projects
    quadrant-3 Fill-ins
    quadrant-4 Thankless tasks
    Syntax highlight: [0.2, 0.8]
    Layout sliders: [0.3, 0.7]
    Pan & Zoom: [0.4, 0.75]
    OAuth login: [0.7, 0.85]
    AI generation: [0.85, 0.9]
    Dark mode: [0.25, 0.4]

XY Chart

A combined bar/line chart with explicit x-axis categories and y-axis range. Multiple series can stack on the same chart for comparison.

metrics dashboards
time-series snapshots
before/after comparisons
lightweight reporting

xychart-beta
    title "Monthly Active Users"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Users" 0 --> 5000
    bar [120, 380, 820, 1540, 2900, 4600]
    line [120, 380, 820, 1540, 2900, 4600]

Sankey

A flow diagram where edge thickness encodes magnitude. Nodes and weighted edges are listed line by line — no positioning needed, the layout solver places them.

funnel analysis
energy or material flow
budget allocation
traffic source breakdowns

sankey-beta
    Traffic Sources,Visitors,1000
    Organic Search,Visitors,400
    Direct,Visitors,300
    Social Media,Visitors,200
    Referral,Visitors,100
    Visitors,Sign Up,250
    Visitors,Free Plan,600
    Visitors,Bounce,150
    Free Plan,Pro Upgrade,80
    Free Plan,Active Free,520

Mindmap

A radial outline that branches from a single root concept. Indentation defines hierarchy; node shape is set by wrapping the label in `[]`, `()`, or `(())`.

brainstorming
note hierarchies
feature breakdowns
meeting summaries

mindmap
  root((MermanDraw))
    Editor
      CodeMirror 6
      Monokai Pro theme
      Mermaid syntax highlight
    Diagrams
      7 themes
      Layout sliders
      Pan & Zoom
    Export
      SVG
      PNG
    Share
      Shareable link
      OG preview
      180-day expiry

Block

A grid of labelled blocks with arrows for relationships. Use `columns N` to set the grid width and `space` to leave gaps. Good for boxes-and-arrows architecture sketches.

high-level architecture
system block diagrams
service grouping
context maps

block-beta
    columns 3
    A["Frontend
(Astro)"] B["API
(Hono)"] C["Storage
(D1/R2)"]
    space D["KV Cache"] space
    E["CDN
(Cloudflare)"] F["Pages
Functions"] G["Workers
Cron"]
    A --> B
    B --> C
    B --> D
    E --> A
    F --> B
    G --> C

Architecture

A topology of services grouped into clouds, with explicit edge directions (`R`, `L`, `T`, `B`). Built-in icon set covers internet, server, database, disk, and cloud nodes.

cloud-architecture diagrams
deployment topologies
microservice maps
infrastructure overviews

architecture-beta
    group cloud(cloud)[Cloudflare]

    service cdn(internet)[CDN] in cloud
    service pages(server)[Pages] in cloud
    service worker(server)[Worker API] in cloud
    service db(database)[D1 Database] in cloud
    service kv(disk)[KV Store] in cloud
    service r2(disk)[R2 Storage] in cloud

    cdn:R --> L:pages
    pages:R --> L:worker
    worker:R --> L:db
    worker:T --> B:kv
    worker:B --> T:r2

Git Graph

A git history with branches, commits, merges, and tags. Useful for explaining branching strategies or reconstructing a release flow without screenshotting an actual repo.

branching-strategy docs
release flow explanations
merge-conflict tutorials
git workshop slides

gitGraph
    commit id: "init"
    branch feature/themes
    checkout feature/themes
    commit id: "add 7 themes"
    commit id: "layout sliders"
    checkout main
    merge feature/themes
    branch feature/share
    checkout feature/share
    commit id: "share API"
    commit id: "share page OG"
    checkout main
    merge feature/share
    commit id: "v1.0 launch"

ZenUML

An alternative sequence-diagram syntax with explicit lifecycles for Actor, Boundary, Control, and Entity. Nested method calls render as indented blocks rather than separate arrows.

DDD interaction modelling
method-call hierarchies
service collaboration docs
OO sequence flows

zenuml
    title Order Service
    @Actor User
    @Boundary OrderUI
    @Control OrderService
    @Entity OrderDB

    User -> OrderUI.placeOrder(item) {
      OrderUI -> OrderService.createOrder(item) {
        OrderService -> OrderDB.save(order)
        return orderId
      }
      return confirmation
    }

FAQ

What is Mermaid?

Mermaid is a JavaScript-based diagramming and charting tool that turns plain-text code into flowcharts, sequence diagrams, ER diagrams, Gantt charts, and 15 other diagram types. It is the de-facto standard for diagrams that live alongside code: GitHub, GitLab, Notion-with-plugins, and most documentation generators render Mermaid blocks natively. Because the source is text, AI assistants like ChatGPT and Claude generate Mermaid output reliably, and the same source can be diffed, code-reviewed, and version-controlled like any other file.

How do I render Mermaid in a GitHub README?

GitHub renders Mermaid automatically inside fenced code blocks tagged with the language `mermaid`. Wrap your diagram code in three backticks followed by `mermaid`, then close with three backticks. The rendered diagram appears in the README, issues, pull requests, and GitHub Discussions — no extensions or plugins required. If your diagram does not appear, check that the language tag is exactly `mermaid` (lowercase) and that the syntax parses cleanly in the editor on this page.

Can I use Mermaid in Notion?

Notion does not render Mermaid natively as of 2026. The two practical workarounds are: (1) use a Mermaid-supporting code block plugin from the Notion marketplace, or (2) export the rendered diagram from MermanDraw as PNG or SVG and embed the image in your Notion page. The image approach is more reliable for sharing with collaborators who do not have the plugin installed, and SVG keeps the diagram crisp at any zoom level.

Mermaid vs PlantUML — which should I use?

Choose Mermaid for lightweight, markdown-friendly diagrams that render in modern documentation pipelines without a Java runtime. Choose PlantUML when you need diagram types Mermaid does not support (deployment, object, profile diagrams), enterprise-grade theming, or tight integration with legacy tooling. For most modern documentation, AI-assisted generation, and GitHub-hosted projects, Mermaid is the lower-friction choice.

Why does ChatGPT-generated Mermaid often fail to render?

The four most common failures: (1) unescaped special characters inside node labels — wrap labels with parentheses or quotes in double quotes; (2) line breaks inside labels — use `<br/>` instead of `\n`; (3) deprecated keywords from older Mermaid versions — `graph` still works but `flowchart` is preferred; (4) arrow typos like `-->` written as `->` or `–>`. Paste any failing diagram into MermanDraw and the editor surfaces the exact parse error so you can fix it in seconds.