Mermaid Editor Docs
Mermaid is a text-to-diagram language. You write a short snippet of code, the editor renders it as an SVG, and you can export the result as a vector SVG or a portable PNG. The docs below cover every diagram type the editor supports, with a syntax cheat-sheet and a working example for each. Everything renders entirely in your browser.
About Mermaid
Mermaid is a JavaScript library that converts a small, readable syntax into rendered SVG diagrams. It started as a tool for keeping diagrams in version control alongside the code they describe, and grew into one of the most-cited diagramming tools for engineers, technical writers, and AI builders.
The editor on this page bundles the full Mermaid library (vendored, version-pinned, served from this domain) and renders every diagram locally. Nothing you type leaves your device. The same renderer is what powers the Mermaid auto-embed when you convert a Markdown document that contains ```mermaid blocks to HTML, DOCX, or PDF.
Flowchart graph
When to use: any process with steps, decisions, and branches. The default workhorse — anything from a sign-up funnel to a data-pipeline overview.
Syntax cheat-sheet:
graph TD %% TD=top-down, LR=left-right, BT, RL
A[Box] --> B(Round box)
A --> C{Diamond}
C -->|Yes| D[End]
C -->|No| E[Other end]
D --- E %% open line, no arrow
Node shapes: [rect], (round), ([stadium]), [[subroutine]], [(cylinder)], ((circle)), {diamond}, {{hexagon}}, [/parallelogram/].
Tip: keep node IDs short (A, B, C) and put the human label in brackets. Mermaid will dedupe identical IDs across the chart.
Sequence Diagram sequenceDiagram
When to use: showing how a request travels between systems or actors over time — API call chains, login flows, message-passing protocols.
Syntax cheat-sheet:
sequenceDiagram
participant U as User
participant S as Server
U->>S: GET /me
S-->>U: 200 + payload
Note over U,S: Session refreshed
U->>+S: POST /logout
S-->>-U: 204 No Content
Arrow types: -> solid line, --> dashed, ->> with arrowhead, -->> dashed with arrowhead, -x with cross. The +/- on participant names toggles activation bars.
Tip: wrap reply sequences in alt / else / end to show branches, or opt for an optional path.
Class Diagram classDiagram
When to use: object-oriented design — class hierarchies, methods, relationships. Common in software architecture docs and onboarding pages for OOP codebases.
Syntax cheat-sheet:
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+String breed
+bark()
}
Animal <|-- Dog %% inheritance
Animal "1" o-- "*" Owner %% aggregation
Animal "1" *-- "1" Heart %% composition
Visibility prefixes: + public, - private, # protected, ~ package-private.
Tip: long classes get noisy fast. Split into multiple sub-diagrams by domain instead of one mega-chart.
State Diagram stateDiagram-v2
When to use: any finite-state machine — order lifecycles, document approval flows, connection state. Especially handy when you want to enumerate which transitions are legal.
Syntax cheat-sheet:
stateDiagram-v2
[*] --> Idle
Idle --> Running: start
Running --> Idle: stop
Running --> Failed: error
Failed --> Idle: reset
Running --> [*]: complete
[*] is the entry/exit pseudostate. Compose nested states with state Outer { ... } blocks.
Tip: always show the terminal state (--> [*]). Readers infer correctness from seeing where a state machine ends.
ER Diagram erDiagram
When to use: data modeling — tables, columns, cardinality. The standard format for explaining a relational schema in onboarding docs.
Syntax cheat-sheet:
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
CUSTOMER {
string name
string email
}
ORDER {
int id
date placed
}
Cardinality: || exactly one, o| zero or one, }| one or more, }o zero or more. Read left-to-right.
Tip: name the relationship with a verb (places, contains). It reads as a sentence: "A customer places orders."
Gantt Chart gantt
When to use: project timelines — sprints, releases, parallel tracks of work. Mermaid Gantt is light enough for a README; for serious project-management you would still go to Linear or Jira.
Syntax cheat-sheet:
gantt
title Sprint Plan
dateFormat YYYY-MM-DD
section Design
Wireframes :a1, 2026-01-01, 5d
Mockups :a2, after a1, 3d
section Build
Implement :b1, after a2, 7d
Task syntax: name :[id], [start | after other-id], [duration | end-date]. The crit keyword marks a task critical-path; milestone renders it as a diamond.
Tip: use section headers to group tracks. Without sections, every task piles on one row.
Pie Chart pie
When to use: compact percentage breakdowns — quick visualization of share or distribution. Avoid for serial comparisons (bar charts are better).
Syntax cheat-sheet:
pie title Browser Share
"Chrome" : 65
"Safari" : 18
"Firefox" : 10
"Other" : 7
Values can be any number; Mermaid normalizes the percentages. Use showData after pie on the first line to display the raw number in each slice label.
Tip: if you have more than five slices, switch to a bar chart in a different tool — pie charts get unreadable past that.
Git Graph gitGraph
When to use: explaining a branching strategy — gitflow, trunk-based, feature-flag merges. Great for onboarding docs and post-mortems on branch confusion.
Syntax cheat-sheet:
gitGraph
commit
commit
branch develop
commit
commit
checkout main
merge develop
commit
Commit IDs auto-generate. Use commit id: "feat-xyz" to set a custom one, and tag: "v1.0" to mark a release.
Tip: Mermaid renders Git Graphs horizontally by default. Add %%{init: { "gitGraph": {"mainBranchOrder": 0}} }%% at the top to control branch order — though our editor strips runtime init directives for safety, so this only applies in your own renderer.
Mind Map mindmap
When to use: hierarchical brainstorming, topic decomposition, table-of-contents-style outlines. Mermaid mind maps were added in v9.6 and are simple by design.
Syntax cheat-sheet:
mindmap
root((Big idea))
Branch 1
Subtopic A
Subtopic B
Branch 2
Subtopic C
Branch 3
Subtopic D
Subtopic E
Indentation is significant — each level of indent creates a child. Root node shapes: ((rounded)), (cloud), {{hexagon}}, )bang(.
Tip: mind maps are wider than tall. If you have more than ~5 branches, the diagram overflows on mobile — consider splitting into two.
User Journey journey
When to use: product flows from a user's perspective with a satisfaction rating per step. Common in UX docs and onboarding-flow critiques.
Syntax cheat-sheet:
journey
title User signs up
section Discovery
Lands on homepage: 5: User
Reads pricing: 4: User
section Signup
Fills form: 3: User
Confirms email: 4: User, System
First login: 5: User
Each step: label: score (1–5): actors. Scores render as little face icons; the actor list appears under each step.
Tip: use scores honestly. A journey diagram with all 5s tells nobody anything. Real product critique surfaces the 1s and 2s.
Security & Privacy
The editor locks Mermaid to securityLevel: 'strict' and strips any %%{init: ...}%% directive from your input before rendering. That blocks the documented Mermaid escape hatches: in-document securityLevel overrides, raw-HTML labels, and click-directive JavaScript execution. The rendered SVG is post-processed through a Mermaid-aware sanitizer that removes <script>, <iframe>, <object>, <embed>, every on* event-handler attribute, and any href whose scheme is not in http, https, or mailto.
The library itself is pinned to a specific version (>=11.10.0, which closes all known XSS and CSS-injection CVEs as of writing) and vendored from this domain — no third-party CDN, no Mermaid telemetry, no network call after the initial library load. The diagram source you type never leaves your browser. The same renderer is what bakes Mermaid PNGs into your downloaded HTML, DOCX, and PDF files.