Post

Mermaid draws diagrams

Text to diagrams for a better documentation

Mermaid draws diagrams

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:


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.

This post is licensed under CC BY 4.0 by the author.