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.