Mermaid

Mermaid is an amazing tool for making diagrams and charting by using plain text.

In particular, Mermaid.js is a scripting language whose plain text syntax allows you to represent different types of diagrams, even very complex ones.

The Mermaid project was created and is maintained by Knut Sveidqvist.

Also contributing to the project is Ashish Jain who is co-author with Knut Sveidqvist of the book titled “The Official Guide to Mermaid.js: Create complex diagrams and beautiful flowcharts easily using text and code”, Packt Publishing, 2021.

In the mentioned book, Knut Sveidqvist reveals the reason for the name “Mermaid” and precisely:

First, let’s go over some background. The idea for Mermaid came about after I tried to make a small update to a diagram within a document, a task that ended up taking a surprising amount of time. It turned out that the source file for the diagram was nowhere to be found, so the diagram had to be redrawn from scratch. This made me wonder how we could have a complete document in a text format, with document text and images in the same text file. Due to this, we came up with Markdown in combination with a new utility for rendering diagrams from text. Later the same evening, I sat down in my living room to start this new side project – a new graph rendering library – while my kids were watching The Little Mermaid on TV. And from this, the somewhat whimsical name for the software was born: Mermaid1.

In 2019 Mermaid won the JS Open Source Award as “The Most Exciting Use of Technology” with the motivation “Unique and unconventional use of JavaScript: a mix of original software and technologies that make the language shine and boost the development.”.

Currently, the Mermaid project involves numerous contributors.

Mermaid and Markdown

Mermaid.js can be used with its integrations in several contexts but here we will focus on its use with Markdown.

Some Markdown editors, among which we mention Typewriter and Taio which we have already dealt with, allow you to use the Mermaid specification through its non-complex syntax.

The merit of the work of the developers was to use simple text together with the markup of Markdown (and CommonMark) to simplify the creation of diagrams and graphs, even complex ones.

How do you create a diagram with Mermaid?

Within a Markdown editor that supports Mermaid, it is possible to write lines of code as in the example below:

mermaid 
pie
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5

At the beginning of the code block, declare that this is a Mermaid script using mermaid.
In the example shown, the second line identifies a pie chart via the pie declaration, while the subsequent lines indicate the values.

This small block of code generates the image shown below.


pie title Key elements in Product X "Calcium" : 42.96 "Potassium" : 50.05 "Magnesium" : 10.01 "Iron" : 5

Let’s take another example.

Wanting to realize a sequence diagram (diagram of interaction that shows how the processes operate between them and in which order), we will use the following script:

mermaid
sequenceDiagram
    participant A as Alice
    participant J as John
    A->>J: Hello John, how are you?
    J->>A: Great!

Alice says to John (the direction between speaker and listener is indicated with an arrow in Mermaid syntax is ->> from Alice to John) “Hello, how are you?” (Hello John, how are you?).

John replies “Great!” (again, the ->> arrow indicates the direction of the message from John to Alice).

The graphical result will be as follows:

sequenceDiagram participant A as Alice participant J as John A->>J: Hello John, how are you? J->>A: Great!

The same applies, for example, to a flowchart, using the following code:

mermaid
flowchart TD
    A[Start] --> B{Is it?}
    B -- Yes --> C[OK]
    C --> D[Rethink]
    D --> B
    B -- No ----> E[End]

Graphically we will have:

flowchart TD A[Start] --> B{Is it?} B -- Yes --> C[OK] C --> D[Rethink] D --> B B -- No ----> E[End]

As you can see, although we have given simple examples, the syntax of Mermaid is not complex and can be described in plain text.

Undoubtedly, you can make very complex diagrams and graphs depending on the descriptions that will be needed.

We have used Mermaid to generate class diagrams for our project DAPPREMO according to the UML2 language (Unified Modeling Language and among many, for example, we have obtained the following result:

classDiagram PdP <|-- GDPR PdP <|-- C_Privacy PdP <|-- Etica PdP: +String legislazione PdP: +String Europa PdP: +isRegolamento(sì) PdP: +isDirettiva(sì) PdP: +isConvenzioni(sì) PdP: +isSoftLaw(sì) PdP: +int articoli class Etica{ +String Filosofia +Norme(nessuna) +principi(diversi) } class GDPR{ +String Regolamento +ambito_applicazione() +int articoli } class C_Privacy{ +String D_Legislativo +ambito_applicazione() +int articoli }

Mermaid is undoubtedly a powerful resource that relies on the use of plain text as it is for Markdown as well.

You can access an online editor if you don’t have a Markdown editor that supports Mermaid.

The developers of Mermaid have created and made available an online editor for Mermaid, which can be found here: https://mermaid.live.

The online editor also allows you to save the diagram or graph in PNG or SVG format.

Mermaid, as mentioned, is a powerful tool, but the learning curve does not seem very steep, especially if you consult the online guide which describes the syntax for each type of diagram and graph.

Alternatively, you can learn more about Mermaid by purchasing the book mentioned at the beginning of this post.

In any case, the following solutions are currently available:

Mermaid and its integrations

Another aspect of enormous importance is the integration of Mermaid with other systems, among which, in particular, it is worth mentioning Hugo since version 0.93.0.

Currently, as this page shows, they have native support for Mermaid:

There are, however, further numerous integrations to Mermaid, as described on the cited page for the following categories:

There are also extensions for popular browsers (e.g. Firefox) available.

In conclusion, Mermaid represents a powerful tool and kudos to developers.

Happy Mermaid to everyone!

If this resource was helpful, you could contribute by

Buy me a coffee

Or donate via

Liberapay


Follow us on Mastodon

Stay tuned!

  1. Mermaid represents an aquatic creature that is half woman and half fish. ↩︎

  2. On UML, you can see https://www.uml-diagrams.org/ ↩︎