Mermaid: a powerful tool for making diagrams and graphs with Markdown

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](https://www.amazon.it/gp/product/B098KHTVJ2/ref=dbs_a_def_rwt_hsch_vapi_tkin_p1_i0)*”, 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: Mermaid.

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](https://notes.nicfab.it/en/posts/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.

see here the diagram: https://notes.nicfab.it/en/posts/mermaid/#mermaid

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:

see here the diagram: https://notes.nicfab.it/en/posts/mermaid/#mermaid

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:

see here the flowchart: https://notes.nicfab.it/en/posts/mermaid/#mermaid

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 UML** language ( Unified Modeling Language and among many, for example, we have obtained the following result:

see here the class diagram: https://notes.nicfab.it/en/posts/mermaid/#mermaid

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:

• Flowchart
• Sequence diagram
• Class Diagram
• State Diagram
• Entity Relationship Diagram
• User Journey
• Gantt
• Pie Chart
• Requirement Diagram

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:

• GitLab (Native support)
• Azure Devops (Native support)
• Tuleap (Native support)
• Joplin (Native support)
• Notion (Native support)

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

• Productivity
• CRM/ERP/Similar
• Blogs
• CMS
• Communication
• Wikis
• Editor Plugins
• Document Generation
• Browser Extensions
• Others

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!

Stay tuned!

Originally published at https://notes.nicfab.it on March 22, 2022.

The article is also available in Italian.