I use mermaid to make graphs and diagrams all the time for productivity, documentation and discussion purposes. There are plenty of visual tools out there that allow you to drag lines and shapes around to your hearts content. However sometimes the tools get in the way because you have to fiddle with layout and misbehaving connector lines.

Years ago I came across the DOT language which describes mathematical graphs. Now bear with me, I know math is boring but we don't have to understand the math to benefit from it. If I oversimplify it a graph allows you to describe a relation between objects. So object A relates (points) to object B.

Along with DOT I found GraphViz which visualizes these graphs. Now the cool thing is that this visualization handles all the layout and connector lines for you. It makes sure everything is connected as described. It also tries to ensure none of the lines cross and space is used efficiently by having the tool handle the pretty pictures you can focus on describing the items on your graph and how they relate.

Markdown and the web

Both DOT and GraphViz were command-line tools and could be tricky to get going everywhere. This is where mermaid comes in. It uses a markdown inspired syntax and is available as a JavaScript library for easy installation. GitHub supports it directly in their README files these days. There is also great support in VSCode for the graph syntax and markdown previews or even stand-alone previews.

What does it look like

If you want make a simple diagram you need only declare the type of graph and some items. Here's an example:

flowchart LR
    A --> B
    B --> C
    C --> D

The flowchart LR says we want a flowchart going from Left to Right. Alternative we could use flowchart TD to render it top down.

Now if we re-order the relations and add some more mermaid will render this quite neatly:

flowchart LR
    A --> B
    A --> D
    B --> C
    B --> D
    C --> D

Quickly typing out items like this can be quite handy for mind mapping sessions.

Something more useful

The flowchart name kind of gave it away but that mermaid graph is intend to create flowcharts. We can add names and shapes to object using brackets and accolades. Adding text to the connector lines is also possible. With these options combined we can make a decision flow:

flowchart TD
    A((Welcome))
    B{Shall we?}
    C((Fair enough))
    D[Left foot forward]
    E{Keep going?}
    F((Thanks for trying))
    G[Right foot forward]
    H((You were amazing))
​
    A --> B
    B -->|No| C
    B -->|Yes| D
    D --> E
    E -->|No| F
    E -->|Yes| G
    G --> H

I often end up adding these to documentation for a quick visual overview of an application process flow.

The added benefit of the graph being text based means it can easily be added to source management systems like git. This gives us an easier way to track changes to diagrams in both a visual and non-visual way.

So what else can mermaid do?

Well there are more graph types of course. Need a quick pie chart?

pie showData
    title Would you like some pie?
    "Yes please": 82
    "I'll pass": 18

Maybe you still like old school databases and want en Entity Relation diagram?

erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        string id
        string name
    }
    ORDER {
        int id
        string address
    }

And there are many more like:

* Class diagrams

* Gantt diagrams

* Sequence diagrams

* State diagrams

Checkout the mermaid documentation for all the options.

Summary

Not everyone organizes their thoughts in the same way. Tools like mermaid provide options for those of us that don't like wrangling a mouse to convey our thoughts in a visual way. Thanks for taking the time to read and I hope mermaid can be of use to some of you.