Mermaid diagrams

Famously an picture is worth a thousand words. That may or may not be true but a diagram can definitely help explain something. There’s plenty of software and online tools to help with this but, in my experience, making a diagram can still take a lot of time. It’s good to do but if you could do it faster your more likely to make one.

Mermaid is a diagramming tool that also supports scripts. It can be integrated into markdown and is available on github so you can see the diagrams in your documentation directly. Handily for me there is also a WordPress block, MerPress. I also like the idea of generating these automatically in, say, as part of documentation.

Different chart types can have different syntax depending on the needs of the chart. That’s useful but it looks like it leads to some inconsistencies. Here are a bunch of examples but there’s even more on the Mermaid site.

Boxes and lines

Graphs

Lets start with something basic: nodes, edges, arrows and labels:

```mermaid
graph LR;

A[Facing North]--->B
A-->C
B(Turn right)--->F[Facing East]
C(Turn left)-->D
D(Turn left)-->E
E(Turn left)-->F
```

becomes:

graph LR;

A[Facing North]--->B
A-->C
B(Turn right)--->F[Facing East]
C(Turn left)-->D
D(Turn left)-->E
E(Turn left)-->F

Flowchart

Lets make it slightly more complicated:

```mermaid
flowchart LR

A[Facing North]-->B
B{Waste time}-->|No| C
B-->|Yes| D
C(Turn right)--->G[Facing East]
D(Turn left)-->E
E(Turn left)-->F
F(Turn left)-->G
```

flowchart LR

A[Facing North]-->B
B{Waste time}-->|No| C
B-->|Yes| D
C(Turn right)--->G[Facing East]
D(Turn left)-->E
E(Turn left)-->F
F(Turn left)-->G

State diagram

```mermaid
stateDiagram-v2

direction LR
[*] --> North
North --> East : Right
North --> West : Left
West --> South : Left
South --> East : Left
East --> [*]
```

stateDiagram-v2

direction LR
[*] --> North
North --> East : Right
North --> West : Left
West --> South : Left
South --> East : Left
East --> [*]

Mathematical

Pie charts

These could be useful although they may be limited compared to a chart specific WordPress plugin.

```mermaid
pie

title Household pet ownership in UK
"Dogs" : 31
"Cats" : 26
"Rabbits" : 2.8
"Birds" : 2.3
"Hamsters" : 2.1
"Guinea pigs" : 1.8
```

pie

title Household pet ownership in UK
"Dogs" : 31
"Cats" : 26
"Rabbits" : 2.8
"Birds" : 2.3
"Hamsters" : 2.1
"Guinea pigs" : 1.8

Bar chart

```mermaid
xychart-beta

title "Historic pet ownership in UK"
x-axis [2011-12, 2012-13, 2013-14, 2014-15, 2015-16, 2016-17, 2017-18, 2018-19, 2019-20]
y-axis "Percentage pet ownership" 0 --> 100
bar [47, 48, 47, 46, 40, 44, 45, 40, 41]
line [47, 48, 47, 46, 40, 44, 45, 40, 41]
```

xychart-beta

title "Historic pet ownership in UK"
x-axis [2011-12, 2012-13, 2013-14, 2014-15, 2015-16, 2016-17, 2017-18, 2018-19, 2019-20]
y-axis "Percentage pet ownership" 0 --> 100
bar [47, 48, 47, 46, 40, 44, 45, 40, 41]
line [47, 48, 47, 46, 40, 44, 45, 40, 41]

Quadrant chart

```mermaid
quadrantChart

title Which pet to get?
x-axis Less work --> More work
y-axis Less cute --> More cute
quadrant-1 Maybe
quadrant-2 Yes
quadrant-3 Maybe
quadrant-4 No
Toad: [0.45, 0.23]
Dog: [0.57, 0.69]
Snake: [0.78, 0.34]
Frog: [0.40, 0.34]
Cat: [0.35, 0.78]
```

quadrantChart

title Which pet to get?
x-axis Less work --> More work
y-axis Less cute --> More cute
quadrant-1 Maybe
quadrant-2 Yes
quadrant-3 Maybe
quadrant-4 No
Toad: [0.45, 0.23]
Dog: [0.57, 0.69]
Snake: [0.78, 0.34]
Frog: [0.40, 0.34]
Cat: [0.35, 0.78]

Time based diagram

Sequence diagram

```mermaid
sequenceDiagram

User->>Browser: Enters login credentials
Browser->>WebServer: Sends login request
WebServer->>Database: Verifies credentials
alt Credentials valid
    Database-->>WebServer: Returns user data
    WebServer-->>Browser: Sends authentication token
    Browser-->>User: Displays successful login
else Credentials invalid
    Database-->>WebServer: Returns error
    WebServer-->>Browser: Sends authentication failure
    Browser-->>User: Displays error message
end
```

sequenceDiagram

User->>Browser: Enters login credentials
Browser->>WebServer: Sends login request
WebServer->>Database: Verifies credentials
alt Credentials valid
    Database-->>WebServer: Returns user data
    WebServer-->>Browser: Sends authentication token
    Browser-->>User: Displays successful login
else Credentials invalid
    Database-->>WebServer: Returns error
    WebServer-->>Browser: Sends authentication failure
    Browser-->>User: Displays error message
end

Gantt chart

```mermaid
gantt

title Website Redesign Project
dateFormat  YYYY-MM-DD
section Planning
Requirements Gathering     :a1, 2024-06-01, 5d
Project Plan               :a2, after a1, 3d
section Design
Wireframe Design           :b1, 2024-06-07, 4d
Prototype Design           :b2, after b1, 5d
section Development
Frontend Development       :c1, 2024-06-16, 7d
Backend Development        :c2, after c1, 7d
section Testing
Testing and Fixes          :d1, 2024-06-30, 5d
section Deployment
Deployment                 :e1, 2024-07-06, 2d
```

gantt

title Website Redesign Project
dateFormat  YYYY-MM-DD
section Planning
Requirements Gathering     :a1, 2024-06-01, 5d
Project Plan               :a2, after a1, 3d
section Design
Wireframe Design           :b1, 2024-06-07, 4d
Prototype Design           :b2, after b1, 5d
section Development
Frontend Development       :c1, 2024-06-16, 7d
Backend Development        :c2, after c1, 7d
section Testing
Testing and Fixes          :d1, 2024-06-30, 5d
section Deployment
Deployment                 :e1, 2024-07-06, 2d

Timeline

```mermaid
timeline

2002 : LinkedIn
2004 : Facebook
     : Google
2005 : Youtube
2006 : Twitter
```

timeline

2002 : LinkedIn
2004 : Facebook
     : Google
2005 : Youtube
2006 : Twitter

Git graph

```mermaid
gitGraph

commit id: "Initial commit"
commit id: "Added basic structure"
branch develop
checkout develop
commit id: "Implemented feature"
commit id: "Fixed bug in feature"
checkout main
merge develop
commit id: "Refactored codebase"
commit id: "Released v2.0.0"
```

gitGraph

commit id: "Initial commit"
commit id: "Added basic structure"
branch develop
checkout develop
commit id: "Implemented feature"
commit id: "Fixed bug in feature"
checkout main
merge develop
commit id: "Refactored codebase"
commit id: "Released v2.0.0"

Relationship diagram

Class diagram

```mermaid
classDiagram

direction LR
class Car {
    - make: string
    - model: string
    - year: int
    + accelerate(): void
    + brake(): void
}
class Person {
    - name: string
    - age: int
    + walk(): void
    + talk(message: string): void
}
class Engine {
    - cylinders: int
    - horsepower: int
    + start(): void
    + stop(): void
}
Car "1" -- "1" Engine : has
Person <-- Car : drives
```

classDiagram

direction LR
class Car {
    - make: string
    - model: string
    - year: int
    + accelerate(): void
    + brake(): void
}
class Person {
    - name: string
    - age: int
    + walk(): void
    + talk(message: string): void
}
class Engine {
    - cylinders: int
    - horsepower: int
    + start(): void
    + stop(): void
}
Car "1" -- "1" Engine : has
Person <-- Car : drives

Entity-relationship diagram

```mermaid
erDiagram

CUSTOMER }|..|{ DELIVERY-ADDRESS : has
CUSTOMER ||--o{ ORDER : places
CUSTOMER ||--o{ INVOICE : "liable for"
DELIVERY-ADDRESS ||--o{ ORDER : receives
INVOICE ||--|{ ORDER : covers
ORDER ||--|{ ORDER-ITEM : includes
PRODUCT-CATEGORY ||--|{ PRODUCT : contains
PRODUCT ||--o{ ORDER-ITEM : "ordered in"
```

erDiagram

CUSTOMER }|..|{ DELIVERY-ADDRESS : has
CUSTOMER ||--o{ ORDER : places
CUSTOMER ||--o{ INVOICE : "liable for"
DELIVERY-ADDRESS ||--o{ ORDER : receives
INVOICE ||--|{ ORDER : covers
ORDER ||--|{ ORDER-ITEM : includes
PRODUCT-CATEGORY ||--|{ PRODUCT : contains
PRODUCT ||--o{ ORDER-ITEM : "ordered in"

Mindmap

```mermaid
mindmap
  Overview
    Project Goals
      Improve User Interface
      Enhance Performance
    Timeline
      Q1 2024
      Q2 2024
    Development
      Frontend
        UI Design
        Client-side Logic
      Backend
        Server Setup
        Database Integration
    Testing
      Unit Testing
      Integration Testing
    Deployment
      Server Deployment
      Database Migration
```

mindmap
  Overview
    Project Goals
      Improve User Interface
      Enhance Performance
    Timeline
      Q1 2024
      Q2 2024
    Development
      Frontend
        UI Design
        Client-side Logic
      Backend
        Server Setup
        Database Integration
    Testing
      Unit Testing
      Integration Testing
    Deployment
      Server Deployment
      Database Migration

In the end

I haven’t had a chance to use this in anger. It definitely has a few rough edges. There are some visual glitches and more consistency across types would be nice. However this was really quick which makes it easier to throw something in. It’s definitely got some possibilities and I’ll try to use it in the blog.