Mermaid draws diagrams
Text to diagrams for a better documentation
When it comes to documentation, my goal is to explain the ideas and design into something easiest way possible to comprehend. One answer is diagrams because one picture says more than thousand words.
Introduce Mermaid
In case you don’t know Mermaid before, Mermaid is a script in Markdown to render diagrams and flowcharts. We can write Mermaid diagram in Markdown files and Github supports it so we can include our diagrams in README page to increase readability.
Here is Mermaid’s official website.
In order to write and preview the diagrams, we can start writing in this site.
Or install Mermaid preview plugins in your favorite IDEs, such as:
- VSCode: Mermaid Chart by mermaidchart.com
- VSCode: Markdown Preview Mermaid Support by Matt Bierner
- Neovim: markdown-preview.nvim by iamcco
Syntax of Mermaid
Mermaid supports many diagram types. Each type has its own pattern but we can start from this in a Markdown file.
1
2
3
4
5
6
7
8
9
```mermaid
---
title: some title
config:
some: config
---
<diagram type>
<diagram content>
```
Let’s take a look at some sample diagrams.
Examples of Mermaid diagrams
Flowchart
A very basic one. I usually have it when it comes to quick presentation during meetings.
For example:
1
2
3
4
5
6
7
```mermaid
---
title: "Form filling workflow"
---
flowchart TD
user -- "fill form" --> front["front page"] -- "send data" --> api --> database
```
It will be rendered as:
---
title: "Form filling workflow"
---
flowchart TD
user -- "fill form" --> front["front page"] -- "send data" --> api --> database
Sequence diagram
I often use it to describe how the services and people in each party communicate with each other.
For example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
```mermaid
---
title: "Form filling workflow"
---
sequenceDiagram
autonumber
actor User
participant Frontend
participant API
participant Database
User->>Frontend: Fill form
Frontend->>API: Send data
API->>Database: Save data
Database-->>API: Acknowledge
API-->>Frontend: Success response
Frontend-->>User: Show success message
```
---
title: "Form filling workflow"
---
sequenceDiagram
autonumber
actor User
participant Frontend
participant API
participant Database
User->>Frontend: Fill form
Frontend->>API: Send data
API->>Database: Save data
Database-->>API: Acknowledge
API-->>Frontend: Success response
Frontend-->>User: Show success message
Entity Relationship Diagram
A database relation diagram.
For example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
```mermaid
---
title: form filling er-diagram
---
erDiagram
USER |o--o{ FORM : fills
FORM ||--|{ QUESTION : contains
USER {
string id PK
string email
}
FORM {
string id PK
string user_id FK
}
QUESTION {
string id PK
string form_id FK
string question_text
string question_type
}
```
---
title: form filling er-diagram
---
erDiagram
USER |o--o{ FORM : fills
FORM ||--|{ QUESTION : contains
USER {
string id PK
string email
}
FORM {
string id PK
string user_id FK
}
QUESTION {
string id PK
string form_id FK
string question_text
string question_type
}
Gantt chart
A simple timeline for project planning.
For example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
```mermaid
---
title: Survey and design plan
---
gantt
dateFormat YYYY-MM-DD
axisFormat %b-%d
excludes weekends
section Get requirements
Survey : req1, 2025-01-01, 2025-01-10
Survey reports: req2, after req1, 3d
section Design
Meeting for design: crit, active, des1, 2025-01-16, 2025-01-20
Design proposal : after des1, 11d
```
---
title: Survey and design plan
---
gantt
dateFormat YYYY-MM-DD
axisFormat %b-%d
excludes weekends
section Get requirements
Survey : req1, 2025-01-01, 2025-01-10
Survey reports: req2, after req1, 3d
section Design
Meeting for design: crit, active, des1, 2025-01-16, 2025-01-20
Design proposal : after des1, 11d
Mindmap
Great for brainstorming and organize ideas.
For example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
```mermaid
---
title: "How should our new service look like?"
---
mindmap
root((Our new service))
[target groups]
schools
universities
[platform]
android app
ios app
[Purposes]
class organization
homework management
exam reports
```
---
title: "How should our new service look like?"
---
mindmap
root((Our new service))
[target groups]
schools
universities
[platform]
android app
ios app
[Purposes]
class organization
homework management
exam reports
Repo
I’ve create a repo for more Mermaid diagrams here.
