Mermaid

If you want to simplify your documentation and avoid using complex tools like Visio, Dia, or Inkscape for displaying charts and diagrams, Mermaid [1] might be just right for you.

Mermaid, which is based on JavaScript, is similar to open source tools such as Graphviz [2] and JS Sequence Diagrams [3]. These tools generate flow charts and other useful diagrams based on simple text-based commands. Mermaid focuses on UML sequence diagrams, and it supports different output styles that are reminiscent of manual drawings.

Mermaid follows the minimalist concept of Markdown and AsciiDoc formats. This approach opens the door to automated document generation and website integration. The Mermaid project is still relatively unpolished. As you'll learn in this article, the local version has some issues that make it hard to depend on for real production work, but you can use the online Mermaid Live Editor at the project website [4] to generate diagrams and explore the Mermaid command syntax.

The Mermaid project is developed and maintained by Scandinavian Knut Sveidqvist and is licensed under the MIT license. The development is a community effort anchored by the project page on GitHub [1].

In Detail

Mermaid is available as a standalone tool for the command line and as a JavaScript library for website integration. Using the Live Editor on the Mermaid website, you can test the Mermaid functions before you install to learn what the description language can do. Listing 1 contains the flowchart with which Figure 1 was created.

§§nonumbers
graph TD;
A[Move] -->|Define Date| B(Rent a van from the moving company);
B --> C{Pack boxes};
C -->|15 boxes| D[Livingroom];
C -->|5 boxes| E[Kitchen/Bath];
C -->|4 boxes| F[Bedroom];

Figure 1: Mermaid only needs a few instructions to create a simple diagram for moving your home.

Mermaid is based on the Markdown text formatting language, but it goes one step further and transfers the Markdown concept to flow, sequence, and Gantt diagrams. The Mermaid syntax is more economical than Graphviz without compromising functionality.

As Listing 1 shows, you can use simple instructions to describe each element in a diagram. You need to terminate each line of the description with a semicolon, but the interpreter is forgiving in case of errors. After declaring the diagram type, the individual nodes and the edges follow; the edges are the references that show how the nodes relate to each other and what they look like.

Additional text and brackets define the basic representation of the nodes, edges, and labels. With the help of Cascading Style Sheets (CSS), you can then put the finishing touches on the image; Mermaid comes with three pre-built templates.

Chart Types

Mermaid offers a visualization feature for graphs or trees, sequences, Gantt and class diagrams, and Git graphs. Each chart is introduced with a keyword, such as graph, sequenceDiagram, or gantt.

For a graph, you also need to specify the reading direction. TD stands for "top down," TB for "top bottom," and BT for "bottom top." RL means "right left," and LR means "left right" (from left to right). Listing 1 describes a graph for a home moving project that you read from top to bottom and that thus has a TD label.

The following examples show how you can use Mermaid to implement various graphical images. All images are taken from the Live Editor on the project's website.

Enter the description in the text field on the left, and the tool generates an image in real time on the right. To use this image in other documents, you can download it as a file in SVG format or take a screenshot of the image.

Graphs and Trees

Figure 2 shows a graph for possible routes from the German city Magdeburg to Dresden. You can read this graph from left to right (LR).

Figure 2: A route generated as a flowchart with Mermaid.

You need to consider several factors when formulating a graph. For example, an edge with an arrowhead has the form --> for the normal line width, ==> produces a thicker line, and -.- produces a dotted line. You do not need to add any spaces between the node text and the beginning or the end of the edge, but spaces do make the description more legible. Enclose the description text for the edge either in pipe characters (Berlin --> | A 13 | Dresden) or write it directly into the edge (Berlin --> A 13 Dresden).

Node identifiers with special characters need to be in quotes. If you enter an identifier in the form D[living room], Mermaid remembers the abbreviation (D in this case), which you can then use as a reference later on. The type of parentheses determines how the node is displayed: Square brackets create rectangles, curly brackets create rhombuses, and round brackets create rectangles with rounded corners.

Sequence Diagram

A sequence diagram describes how processes, programs, instances, or even people interact with each other (Figure 3). The communication sequence follows the sequenceDiagram keyword. The sender and receiver correspond to the nodes in the graphs. Each message is in a single line. You use the arrowhead to indicate who is transmitting something to whom. Place a colon between the recipient and the message, and you can add additional space to improve readability.

Figure 3: In the sequence diagram, Mermaid traces the course of a conversation typical of instant messengers.

Mermaid goes beyond simple sequence diagrams. Other possibilities include notes, activations, loops, conditional blocks, and optional entries. In Figure 4, the weather station sensor used as an example collects data and sends it to the station once a minute, provided it is active and there is a connection to the weather station. If problems occur during transfer, the sensor repeats the data transmission.

Figure 4: The sequence diagram shows a simple log for a weather station with a loop and an if condition.

A loop for repetition consists of a loop-end block. You formulate a condition with alt-else-end. You can add notes with the Note keyword and a position specification. This tells Mermaid whether to place the note in the image to the right or left of the node.

Gantt Diagram

A Gantt bar chart shows the chronological sequence of events and project steps (Figure 5). After the gantt keyword, you assign a program title and specify the dateformat. For each subproject, define a heading using the section keyword; in Figure 5, the three areas are named Weather Data Evaluation, Hardware Procurement, and Documentation.

Figure 5: Representing a project timeline as a Gantt diagram.

For each section of the subproject, assign a title that appears inside the box. If the text does not fit in the box, it will be displayed next to the box. Each section defines an identifier – i.e., a unique name – as well as a position and a time specification. You can use either an exact time or a value of the form after section_name as position specifiers.

Setting Up Mermaid

Mermaid packages are available for some Linux distributions, but other distros haven't yet added the packages to their repositories. See your Linux distro's package manager to see if a package is available.

If you can't find Mermaid in your distro's package repository, you can still install it using the Node Package Manager (npm) [5] from the JavaScript framework Node.js [6]. To set up Node.js 9 and Mermaid under Debian, Ubuntu, or Linux Mint, run the five commands in Listing 2 as an administrative user.

§§nonumbers
# curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -
# apt-get install nodejs
# apt-get install build-essential
# npm install -g mermaid
# npm install -g mermaid-cli

The first two steps install Node.js. The third command loads the build-essential package, which contains important tools for building software. The last two steps set up Mermaid with npm, both as a JavaScript framework and as a command-line tool.

After the installation, you can use the mermaid command, to which you pass the desired output format of the graphic and the file with the diagram description when calling. For example, the following command creates a graphic in PNG format from the source code file flowchart.txt:

$ mermaid --png flowchart.txt

To generate an SVG file instead, specify -s or --svg as the output format parameters. In the case of this example, the generated image file goes by the name of flowchart.png or flowchart.svg.

In our lab, we discovered that the command-line tool offers only a subset of the options offered by the online version. In addition, the generated images differ from the output in the online editor: For example, edge labels and arrowheads are missing. The local Mermaid also constantly trips up over non-standard characters and brackets in descriptions. Another weak point is the design of the diagrams. The command-line tool does not currently let you include your own style sheets. Thus, the output is limited to the three styles provided.

The add-on module mermaid-filter [7], which uses pandoc to help Markdown understand Mermaid statements directly while translating from Markdown to HTML and thus builds the diagrams in the background, could also do with a revision. The description sounds promising, but the installation failed on Debian 8/9. The reason for this remains unclear.

To work around these problems, you can only use the SVG format images generated by the online editor. Automation only partially succeeds; your only option is to prepare the images or turn to Graphviz. If you want to process the output of Mermaid elsewhere in your documents, you must therefore use the basically less suitable PNG format.

Both the online version and the installable version produced faulty vector graphics: Common web browsers display them reasonably correctly, but programs like Gimp, LibreOffice Draw, Inkscape, or Adobe Illustrator can't do anything with them. However, since the less buggy online version only offers SVG as an export format, you have no choice but to continue working with screenshots.

Conclusions

The idea behind Mermaid seems captivating: Graphs and diagrams are compiled in the form of a text description, provided with a style sheet, and then translated into an image. The text format ensures easy composition, and it also enables uncomplicated archiving of the data in a version control system.

Currently, the local version has several problems that cloud the picture, including installation issues, incorrect rendering of special characters, and incorrect edge labels. The online edition also had some issues with unusable vector graphics. The Mermaid project is on the right track, and if you're interested in an easy tool for generating simple charts and diagrams, you'll enjoy exploring and experimenting with the online editor: In its current state, however, Mermaid is not really reliably enough for steady production use.