Mermaid is a text-based diagramming tool for people who would rather write diagrams than drag boxes around a canvas. It uses a Markdown-like syntax to describe flowcharts, sequence diagrams, class diagrams, state machines, timelines, Gantt charts, entity relationship diagrams, and more.
For a technical blog, Mermaid is a very good default. The diagrams live next to the article, they can be reviewed in Git, and they are easy to update when the system changes. Static image diagrams look nice until the first architecture change. Mermaid diagrams are not perfect, but they age much better.
This guide is a practical Mermaid quickstart and cheatsheet for developers, technical writers, and Hugo site owners. It is part of the . For Hugo, rendering depends on your theme or site configuration. More on that later.
Test Diagrams Before Publishing
The easiest workflow is:
- Write the diagram in your Markdown file.
- Paste it into a Mermaid live editor or local preview.
- Fix syntax errors.
- Commit the Markdown source.
- Check the final rendered page.
This avoids the classic problem where a diagram works in one renderer but breaks in another because of a small syntax detail.
Flowchart Syntax
Flowcharts are the most common Mermaid diagram type. Use them for workflows, algorithms, decision trees, and system steps.
Basic Flowchart
this code:
```mermaid
flowchart TD
A[User opens website] --> B{Is user logged in?}
B -->|Yes| C[Show dashboard]
B -->|No| D[Show login page]
```
Is producing diagram:
flowchart TD
A[User opens website] --> B{Is user logged in?}
B -->|Yes| C[Show dashboard]
B -->|No| D[Show login page]
Flowchart Directions
Mermaid flowcharts support several directions:
TD - top to bottom
TB - top to bottom
BT - bottom to top
LR - left to right
RL - right to left
Example:
this code:
```mermaid
flowchart LR
Browser --> CDN
CDN --> WebServer
WebServer --> Database
```
Is producing diagram:
flowchart LR
Browser --> CDN
CDN --> WebServer
WebServer --> Database
For blog articles, LR is often easier to read for architecture diagrams. For step-by-step processes, TD is usually better.
Common Node Shapes
this code:
```mermaid
flowchart TD
A[Rectangle]
B(Rounded rectangle)
C{Decision}
D((Circle))
E[(Database)]
F[[Subroutine]]
```
Is producing diagram:
flowchart TD
A[Rectangle]
B(Rounded rectangle)
C{Decision}
D((Circle))
E[(Database)]
F[[Subroutine]]
Flowchart Arrows
this code:
```mermaid
flowchart LR
A --> B
B --- C
C -.-> D
D ==> E
E -- Label --> F
```
Is producing diagram:
flowchart LR
A --> B
B --- C
C -.-> D
D ==> E
E -- Label --> F
Subgraphs
Use subgraphs to group related parts of a system.
this code:
```mermaid
flowchart LR
subgraph Client
Browser
end
subgraph Backend
API
Worker
end
subgraph Storage
DB[(PostgreSQL)]
Cache[(Redis)]
end
Browser --> API
API --> DB
API --> Cache
API --> Worker
```
Is producing diagram:
flowchart LR
subgraph Client
Browser
end
subgraph Backend
API
Worker
end
subgraph Storage
DB[(PostgreSQL)]
Cache[(Redis)]
end
Browser --> API
API --> DB
API --> Cache
API --> Worker
Subgraphs are powerful, but use them carefully. A diagram with six subgraphs and twenty arrows is usually a sign that the article needs two smaller diagrams.
Sequence Diagram Syntax
Sequence diagrams show communication between actors or services over time.
this code:
```mermaid
sequenceDiagram
participant User
participant App
participant API
participant DB
User->>App: Click login
App->>API: POST /login
API->>DB: Validate credentials
DB-->>API: User record
API-->>App: Access token
App-->>User: Show dashboard
```
Is producing diagram:
sequenceDiagram
participant User
participant App
participant API
participant DB
User->>App: Click login
App->>API: POST /login
API->>DB: Validate credentials
DB-->>API: User record
API-->>App: Access token
App-->>User: Show dashboard
Common Sequence Arrows
-> solid line without arrow
--> dotted line without arrow
->> solid line with arrow
-->> dotted line with arrow
-x solid line with cross
--x dotted line with cross
Activation Bars
Activation bars make it clearer when a participant is doing work.
this code:
```mermaid
sequenceDiagram
participant Client
participant Server
Client->>Server: Request data
activate Server
Server-->>Client: Response
deactivate Server
```
Is producing diagram:
sequenceDiagram
participant Client
participant Server
Client->>Server: Request data
activate Server
Server-->>Client: Response
deactivate Server
Alternatives and Conditions
this code:
```mermaid
sequenceDiagram
participant User
participant API
participant Payment
User->>API: Submit order
alt Payment succeeds
API->>Payment: Charge card
Payment-->>API: Approved
API-->>User: Order confirmed
else Payment fails
Payment-->>API: Declined
API-->>User: Show error
end
```
Is producing diagram:
sequenceDiagram
participant User
participant API
participant Payment
User->>API: Submit order
alt Payment succeeds
API->>Payment: Charge card
Payment-->>API: Approved
API-->>User: Order confirmed
else Payment fails
Payment-->>API: Declined
API-->>User: Show error
end
Sequence diagrams are excellent for API articles. They show not just what components exist, but how they talk to each other.
Class Diagram Syntax
Class diagrams are useful for domain models and object relationships.
this code:
```mermaid
classDiagram
class User {
+string id
+string email
+login()
+logout()
}
class Order {
+string id
+float total
+submit()
}
User "1" --> "*" Order
```
Is producing diagram:
classDiagram
class User {
+string id
+string email
+login()
+logout()
}
class Order {
+string id
+float total
+submit()
}
User "1" --> "*" Order
Class Relationships
<|-- inheritance
*-- composition
o-- aggregation
--> association
-- link
..> dependency
..|> realization
Example:
this code:
```mermaid
classDiagram
Animal <|-- Dog
Animal <|-- Cat
User "1" --> "*" Order
Order *-- OrderItem
```
Is producing diagram:
classDiagram
Animal <|-- Dog
Animal <|-- Cat
User "1" --> "*" Order
Order *-- OrderItem
Class diagrams can become noisy fast. In a blog post, prefer a small domain slice over a full application model.
State Diagram Syntax
State diagrams explain how something changes over time.
this code:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Review: submit
Review --> Published: approve
Review --> Draft: request changes
Published --> Archived: archive
Archived --> [*]
```
Is producing diagram:
stateDiagram-v2
[*] --> Draft
Draft --> Review: submit
Review --> Published: approve
Review --> Draft: request changes
Published --> Archived: archive
Archived --> [*]
Use state diagrams for:
- Order lifecycles
- Deployment states
- Authentication flows
- Background job status
- Content publishing workflows
State diagrams are underrated. They often explain business logic better than a long paragraph.
Entity Relationship Diagram Syntax
Entity relationship diagrams are useful for database models.
this code:
```mermaid
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : appears_in
USER {
string id
string email
}
ORDER {
string id
datetime created_at
}
PRODUCT {
string id
string name
}
```
Is producing diagram:
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : appears_in
USER {
string id
string email
}
ORDER {
string id
datetime created_at
}
PRODUCT {
string id
string name
}
ER Relationship Markers
|| exactly one
o| zero or one
}| one or more
}o zero or more
ER diagrams are best when they explain relationships, not every column. Keep implementation details in migrations or schema docs.
Gantt Chart Syntax
Gantt charts are useful for project timelines.
this code:
```mermaid
gantt
title Documentation Migration Plan
dateFormat YYYY-MM-DD
section Planning
Audit current docs :a1, 2026-06-01, 5d
Define structure :a2, after a1, 3d
section Writing
Rewrite guides :b1, after a2, 10d
Review and publish :b2, after b1, 4d
```
Is producing diagram:
gantt
title Documentation Migration Plan
dateFormat YYYY-MM-DD
section Planning
Audit current docs :a1, 2026-06-01, 5d
Define structure :a2, after a1, 3d
section Writing
Rewrite guides :b1, after a2, 10d
Review and publish :b2, after b1, 4d
Gantt charts are helpful in internal planning posts, but they can age quickly. Use them when the timeline itself is the point.
Timeline Syntax
Timelines are good for release histories, incident writeups, and project summaries.
this code:
```mermaid
timeline
title API Evolution
2024 : REST API launched
2025 : Webhooks added
2026 : Event streaming introduced
```
Is producing diagram:
timeline
title API Evolution
2024 : REST API launched
2025 : Webhooks added
2026 : Event streaming introduced
Use a timeline when order matters more than dependency. If what you care about is the sequence of events rather than how they causally connect, a timeline keeps the focus where it belongs and stays easy to read at a glance.
Pie Chart Syntax
Pie charts are supported, but be careful. They are easy to read when there are only a few categories and the values are clearly different.
this code:
```mermaid
pie title Build Time by Step
"Install dependencies" : 35
"Run tests" : 45
"Build assets" : 20
```
Is producing diagram:
pie title Build Time by Step
"Install dependencies" : 35
"Run tests" : 45
"Build assets" : 20
Opinionated advice: if the values are close or there are more than five categories, use a table instead. A well-formatted table communicates precise numbers more honestly than a pie chart where the slices look nearly identical.
Git Graph Syntax
Git graphs can explain branching strategies and release flows.
this code:
```mermaid
gitGraph
commit
branch feature
checkout feature
commit
commit
checkout main
merge feature
commit
```
Is producing diagram:
gitGraph
commit
branch feature
checkout feature
commit
commit
checkout main
merge feature
commit
This is useful for articles about Git workflows, trunk-based development, release branches, and hotfixes. If you need a quick reference for the underlying branching commands, the is a handy companion when you want to turn the diagram above into a working pipeline.
Publishing Workflow
this code:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Editing
Editing --> Review
Review --> Published
Review --> Editing
Published --> [*]
```
Is producing diagram:
stateDiagram-v2
[*] --> Draft
Draft --> Editing
Editing --> Review
Review --> Published
Review --> Editing
Published --> [*]
Simple Data Model
this code:
```mermaid
erDiagram
AUTHOR ||--o{ POST : writes
POST ||--o{ COMMENT : receives
AUTHOR {
string id
string name
}
POST {
string id
string title
datetime published_at
}
COMMENT {
string id
string body
}
```
Is producing diagram:
erDiagram
AUTHOR ||--o{ POST : writes
POST ||--o{ COMMENT : receives
AUTHOR {
string id
string name
}
POST {
string id
string title
datetime published_at
}
COMMENT {
string id
string body
}
When Not to Use Mermaid
Do not use Mermaid when:
- The diagram needs precise visual layout.
- The design must match a brand system exactly.
- The visual is mostly decorative.
- The diagram has too many nodes to read.
- A screenshot would explain the point better.
- The content changes rarely and needs polish more than maintainability.
Mermaid is excellent for living technical documentation. It is less good for presentation-grade artwork. For document-quality diagrams in print or PDF contexts, LaTeX offers packages like TikZ and pgfplots that give you far greater layout control — the is the quick-reference companion to keep alongside this guide.
The best Mermaid diagrams are not the most complex ones. They are the diagrams that make a concept obvious and remain easy to edit six months later.
Use Mermaid for the diagrams that should live with your documentation. Keep them small, keep them readable, and treat them as part of the source code of your article.
SOCIAL SHARE CARD GENERATOR