Mermaid Diagrams in Markdown
Mermaid turns plain text into diagrams. Tag a fenced code block with mermaid and it renders as a picture — which means your diagrams live in version control, diff like code, and never go stale in a wiki nobody updates.
Every diagram below is rendered live on this page. Copy any snippet into a paste and you will get the same result.
Flowchart
The one you will use most. Declare a direction (`LR` left-to-right, `TD` top-down), then wire nodes together with arrows.
```mermaid
flowchart TD
A[Request received] --> B{Cached?}
B -- Hit --> C[Return cached copy]
B -- Miss --> D[Query database]
D --> E{Found?}
E -- No --> F[404]
E -- Yes --> G[Decompress]
G --> H[Render markdown]
H --> I[Cache and return]
```Bracket shape sets node shape: [box], (rounded), {diamond}, ((circle)). Diamonds read as decisions, so keep them for branches.
Sequence diagram
Shows who talks to whom, in order. Solid arrows (`->>`) are calls, dashed (`-->>`) are responses.
```mermaid
sequenceDiagram
participant U as User
participant B as Browser
participant S as Server
U->>B: Enters password
B->>B: Derive key (PBKDF2)
B->>B: Encrypt content
B->>S: POST ciphertext
S-->>B: Returns paste ID
Note over S: Server never sees<br/>the password
B-->>U: Shareable link
````Note over X` is how you annotate without adding a participant. It is the fastest way to make a diagram explain itself.
State diagram
For anything with modes. `[*]` marks the start and end, and arrows carry the event that causes each transition.
```mermaid
stateDiagram-v2
[*] --> Locked
Locked --> Decrypting: password entered
Decrypting --> Decrypted: key valid
Decrypting --> Error: wrong password
Error --> Decrypting: retry
Decrypted --> [*]
```Worth reaching for whenever a component has a status field. A five-state diagram usually exposes a transition nobody handled.
Class diagram
Types and their relationships. `+` is public, `-` private, and the arrow style encodes the relationship.
```mermaid
classDiagram
class Paste {
+string publicId
+string content
+bool isEncrypted
+Date createdAt
+render() string
}
class EncryptedPaste {
+string salt
+string iv
+decrypt(password) string
}
Paste <|-- EncryptedPaste
````<|--` is inheritance, `*--` composition, `o--` aggregation, `-->` a plain association.
Entity relationship diagram
Database shape. The crow-foot notation on each end sets cardinality — `||` exactly one, `o{` zero or more.
```mermaid
erDiagram
USER ||--o{ PASTE : creates
PASTE ||--o| ENCRYPTION_META : "may have"
PASTE {
int id PK
string public_id UK
text content
bool is_encrypted
timestamp created_at
}
```PK, FK and UK after a column mark primary, foreign and unique keys. Useful in a migration PR where the schema change is the review.
Gantt chart
Timelines without a spreadsheet. Set a date format, group work into sections, and give each task an id so others can depend on it.
```mermaid
gantt
title Release plan
dateFormat YYYY-MM-DD
section Build
Expiry options :done, exp, 2026-01-05, 10d
Edit tokens :active, edit, after exp, 14d
section Ship
Beta : beta, after edit, 7d
Public release :milestone, after beta, 0d
````after <id>` beats hardcoded dates — shift one task and everything downstream moves with it.
Git graph
Branching and merging, drawn out. Handy in a contributing guide where the words "rebase onto main" do most of the confusing.
```mermaid
gitGraph
commit id: "init"
commit id: "add parser"
branch encryption
checkout encryption
commit id: "AES-GCM"
commit id: "key derivation"
checkout main
commit id: "fix tables"
merge encryption
commit id: "release"
```Pie chart
Proportions, declared as label-and-value pairs. Percentages are calculated for you.
```mermaid
pie title Paste content types
"Code snippets" : 42
"Documentation" : 28
"Notes" : 18
"Config files" : 12
```Mindmap
Hierarchy from indentation alone — no arrows to declare. Good for scoping a feature before it has structure.
```mermaid
mindmap
root((Markdown))
Structure
Headings
Lists
Tables
Inline
Bold
Links
Code
Extensions
Math
Diagrams
Footnotes
```Indentation is the whole syntax, so mixing tabs and spaces is the usual reason one of these fails to render.
Timeline
Events against periods. Each period can carry several entries, split with a colon.
```mermaid
timeline
title Markdown, briefly
2004 : Gruber releases Markdown
2009 : Stack Overflow adopts it
2013 : GitHub Flavored Markdown
2014 : CommonMark spec begins
2016 : Mermaid diagrams appear
```User journey
Steps scored one to five, attributed to a person. Makes the low-scoring step in a flow impossible to miss.
```mermaid
journey
title Sharing an encrypted note
section Write
Open the site: 5: User
Paste content: 5: User
Choose a password: 3: User
section Share
Copy the link: 5: User
Send it: 4: User
section Read
Open the link: 5: Recipient
Enter password: 2: Recipient
Read content: 5: Recipient
```The scores are the point. Anything scoring 2 is where people give up.
Quadrant chart
Two axes, four labelled quadrants, points placed on a 0-to-1 scale. The effort-versus-impact conversation, drawn.
```mermaid
quadrantChart
title Roadmap priorities
x-axis Low effort --> High effort
y-axis Low impact --> High impact
quadrant-1 Do now
quadrant-2 Plan carefully
quadrant-3 Skip
quadrant-4 Quick wins
Expiry options: [0.3, 0.8]
View counter: [0.2, 0.35]
Rich editor: [0.85, 0.75]
Paste forking: [0.5, 0.3]
```Share a diagram
Paste Mermaid source here and you get a link that renders the diagram — with export, copy, fullscreen and pan-zoom built in. No signup, and encryption if the architecture is not public.