MERMAID

Mihalis Tsoukalos explains how to use Mermaid to create beautiful technical graphs and diagrams you can reuse and update anywhere.

   OUR EXPERT

Mihalis Tsoukalos is a systems engineer and a technical writer. He’s also the author of Go Systems Programming and Mastering Go, with a third book in the works!

QUICK TIP

If Mermaid isn’t to your liking, try Vega and Vega Lite, which enable you to create graphs and plots. Both grammars are based on D3.js and JavaScript. Learn more about Vega and Vega Lite at https://vega. github.io/ and at https:// github.com/ vega/vega.

The subject of this tutorial is Mermaid, which is a Markdown dialect. Put simply, Mermaid code looks like Markdown code and enables you to create flows, diagrams, charts and more. It’s based on JavaScript that renders the Markdown as code to generate the output, because Markdown doesn’t offer support for drawing. Mermaid is supported by many editors including Microsoft Visual Code and typora, which we’ll cover here. There are also online editors that can render Mermaid code and create the respective output.

Mermaid code is delivered in blocks. The first line of a Mermaid block specifies the type of the plot. Valid values include graph, pie, sequence diagram and flowchart. Each plot type has its own syntax, and it’s much easier to include Mermaid code in Markdown files that use the md file extension (filename.md), which is what we’ll be using for the examples of this tutorial.

A Mermaid block in a Markdown file begins with ```mermaid and ends with ``` – this is the Markdown way of telling that the embedded code has a given property, which in this case is Mermaid. However, Mermaid code can also be saved on its own in files that use the mmd file extension (filename.mmd).

Installing Mermaid… or not!

You don’t need to install Mermaid. All you need is an editor that supports Mermaid to see the output from a Mermaid block. The following is a Markdown file, saved as mermaid.md, with a block in Mermaid format: 

The first line is plain Markdown and generates a title in the output. Then, we declare that we’re creating a graph that’s going to be rendered from the top to the bottom (TD: Top-Down) of the page. Next, we add nodes  and we connect them with other nodes. The --> notation shows that the node on the left is connected to the node on the right. The graph contains four nodes, named A1, S2, A3 and A4. If you want to include more nodes and connections between them, just declare what you want – Mermaid takes care of the output.