Diagram As Code using Mermaid

Documenting in general requires working with some kinds of diagrams, be it application architecture, user flow depictions or any reporting representations like Pie charts and Gantt charts.

The heretofore mechanism has been to include the diagrams as images after creating them on tools like draw.io and such. The biggest drawback with this mechanism is that the workflow for a change to any of the created diagrams is a very arduous one. This leads to a lack of interest in keeping the diagrams up to date further leading to gaps in the overall consistency of the documentation.

This is where Mermaid comes in. True to its beautiful name, `Mermaid` makes the process of creating beautiful diagrams and charts and their further modifications super easy. The word `modifying` becomes crucial here since that is the area we as developers struggle to keep up with.

Like `Infrastructure As Code or IAC`, I would say this is `Diagram As Code or DAC`. Mermaid lets you create diagrams declaratively in Markdown-like syntax. The details lie in plain text and can be easily modified at any point in time and also shared and incorporated into documentation quite easily.

To start creating them, we can work with any `editor` of choice say VS Code or Sublime Text or VIM with the appropriate `mermaid` plugin packages installed.

Mermaid comes with integrations for a whole lot of them. You can find more details on the page here — Mermaid — Integrations

I will be working with VS Code. If you do so too, install this extension `Markdown Preview Mermaid Support` and you will be all set.

Let us look at a few simple examples:

Create a new file in VS Code and select the `language` as `Markdown`.

Let us create a diagram:

In the file that you have created, type in the code below ( as is, including the `tick` marks)

```mermaid
graph TD;
A --> B
```

Now, open up the Preview tab and you should see a simple graph with 2 nodes, connecting from A to B, like this:

There you have it! You have created your first diagram using just textual declarations!

graph — defines the type of diagram that you want to be created.

`TD` indicates a `Top Down` graph. This can be altered to whatever you see fit, like `LR for Left Right` as below

```mermaid
graph LR;
A --> B
```

Should give something like this:

Let us now provide some shape to our nodes.

```mermaid
graph LR;
1[A] --> 2{B}
```

square brackets around a node give a `rectangle` shape and `curly` braces result in a `diamond` shape. When specifying nodes with shapes, you will also need to specify an `identifier` which is just a `name` for nodes like `1` and `2` in this case. This can be anything `alphanumeric`

Shapes of the nodes, the types of arrows ( solid, dotted etc ), labels for arrows and so much more can be created using `Mermaid` quite efficiently. For all the details, you can refer here — Mermaid — Diagram Syntax

We can extend the graph further to indicate some kind of a flow, a flow chart per see.

Below, am trying to depict a simple User login flow :

```mermaid
graph TD
a((User)) --> b[[Login]]
b --> c{Has <br>account?} --> |Yes| d{Credentials Valid?} --> |No| b
c -->|No| e[[Sign Up]] --> b
d -->|Yes| f([Login successful])
```

You should see something like this:

As you can see, the entire flowchart is depicted in a simple textual format. This is where comes the power.

Not just flow charts, Mermaid can be used for creating more advanced diagrams too.

Here’s an example of a simple Pie chart:

All you need to do is mention a `title` for the chart along with the `label` and `value` for the individual pieces of the pie.

```mermaid
pie title Incident Distribution by Priority
“Priority 2”: 5
“Priority 3”: 10
“Priority 4”: 15
```

And you should get something like this in the preview pane:

Isn’t that wonderful and simple?

A `Sequence Diagram` is also something that we come across very frequently which is quite simple to create in `Mermaid` as well.

Here’s one example that depicts a sequence of interactions between two people in a Coffee Shop.

```mermaid
sequenceDiagram
Shyam ->> +Maya: Hello Maya, how are you?
Shyam ->> +Maya: Maya, can you hear me?
Maya ->> +CoffeeDay: One Latte for me
Maya ->> -Shyam: Hi Shyam, I can hear you!
Maya ->> -Shyam: I feel great!
Shyam ->> CoffeeDay: One for me too!
```

Gives you this nice diagram:

All this from a simple markdown data. This is truly awesome!

Mermaid is very powerful and is a great way to incorporate diagrams into any documentation. The cycle time to make the changes and get them reflected is very short and therein lies the use case. Give it a go.

Happy exploring. Until next time, adios!