Drawing on Command
Mermaid
Mermaid lets you create diagrams from simple text-based statements.
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.
Listing 1
Building a Mermaid Flowchart
§§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];
![](/var/linux_magazin/storage/images/issues/2018/212/mermaid/figure-1/728552-1-eng-US/Figure-1_large.png)
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
).
![](/var/linux_magazin/storage/images/issues/2018/212/mermaid/figure-2/728555-1-eng-US/Figure-2_large.png)
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.
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
![Learn More](https://www.linux-magazine.com/var/linux_magazin/storage/images/media/linux-magazine-eng-us/images/misc/learn-more/834592-1-eng-US/Learn-More_medium.png)
News
-
NVIDIA Released Driver for Upcoming NVIDIA 560 GPU for Linux
Not only has NVIDIA released the driver for its upcoming CPU series, it's the first release that defaults to using open-source GPU kernel modules.
-
OpenMandriva Lx 24.07 Released
If you’re into rolling release Linux distributions, OpenMandriva ROME has a new snapshot with a new kernel.
-
Kernel 6.10 Available for General Usage
Linus Torvalds has released the 6.10 kernel and it includes significant performance increases for Intel Core hybrid systems and more.
-
TUXEDO Computers Releases InfinityBook Pro 14 Gen9 Laptop
Sporting either AMD or Intel CPUs, the TUXEDO InfinityBook Pro 14 is an extremely compact, lightweight, sturdy powerhouse.
-
Google Extends Support for Linux Kernels Used for Android
Because the LTS Linux kernel releases are so important to Android, Google has decided to extend the support period beyond that offered by the kernel development team.
-
Linux Mint 22 Stable Delayed
If you're anxious about getting your hands on the stable release of Linux Mint 22, it looks as if you're going to have to wait a bit longer.
-
Nitrux 3.5.1 Available for Install
The latest version of the immutable, systemd-free distribution includes an updated kernel and NVIDIA driver.
-
Debian 12.6 Released with Plenty of Bug Fixes and Updates
The sixth update to Debian "Bookworm" is all about security mitigations and making adjustments for some "serious problems."
-
Canonical Offers 12-Year LTS for Open Source Docker Images
Canonical is expanding its LTS offering to reach beyond the DEB packages with a new distro-less Docker image.
-
Plasma Desktop 6.1 Released with Several Enhancements
If you're a fan of Plasma Desktop, you should be excited about this new point release.