Ask Any (Technical) Mermaid

In the last few years, something of a sea change has hit the world of technical and data graphics, after a similar revolution hit HTML production. The reality for many (perhaps most) people, has been that HTML is a very cumbersome language. Markdown, invented by John Gruber and Aaron Schwarz in 2004, attempted to solve this problem by using simple shortcuts: using a hashtag at the beginning of a line (followed by a space) was indicative of an H1 element, two hashtags started an H2 element and so on. While there were a number of different variants of Markdown over the years, the concept has survived pretty much intactfor nearly twenty years, and has in turn gone on to spawn millions of read.me files in git distributions globally

In a similar vein, one of the older graphical application is the Graphviz library known as DOT, which makes use of an arrow based notation for creating network graphs (often known as ball and arrow diagrams). Not surprisingly, DOT is a fan favorite of the semantic community, and has been used extensively to diagram entity relationships for some time now. Similarly the Javascript based version of LateX known as KateX has been used to create mathematical formulae within web content, typically mapping from simple text expressions to MathML or other more complex encodings.

Introducing Mermaid with Pie (a la mode)

Mermaid follows this tradition. Invented by Knut Sveidqvist, Mermaid is a general purpose language for creating a number of different kinds of diagrams within Markdown. For instance, a very simple Mermaid diagram can be created with just a couple of lines of Mermaid:

pie title Pets adopted by volunteers
    "Dogs" : 112
    "Cats" : 85
    "Ferrets" :42
    "Rabbits" :35
    "Fish":32
    "Rats" : 15
    "Pigs":11

This in turn generates the following pie chart:

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#ff0000',
      'primaryTextColor': '#fff',
      'primaryBorderColor': '#7C0000',
      'lineColor': '#F8B229',
      'secondaryColor': '#ffff00',
      'tertiaryColor': '#0000ff',
      'textColor':'black'
    }
  }
}%%
pie title Pets adopted by volunteers
    "Dogs" : 112
    "Cats" : 85
    "Ferrets" :42
    "Rabbits" :35
    "Fish":32
    "Rats" : 15
    "Pigs":11
    

Note that in WordPress, this functionality is facilitated by a number of different plugins, most notably the Merpress plugin for Mermaid. It is possible to use standard themes for specifying colors, or you can use init directives that control key style parameters, as is done here. For reference sake, the above graph uses the following: block, which needs to precede the diagram itself:

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#ff0000',
      'primaryTextColor': '#fff',
      'primaryBorderColor': '#7C0000',
      'lineColor': '#F8B229',
      'secondaryColor': 'yellow',
      'tertiaryColor': 'blue',
      'textColor':'black'
    }
  }
}%%

More on theming can be found in the Mermaid documentation pages theming subsection. If you are using Gutenberg, once the Merpress plug-in is installed, you can invoke it with /mermaidjs , which lets you write your Mermaid code and preview it in real time.

Network Graphs and Flowcharts

Network graph diagrams and flowcharts show the interconnectedness of various components in a system, and are a staple of semantic work.For instance, consider anadventure game where you want to show all of the items that are in a particular “room”.

The following flowchart illustrates one example of such a graph.

flowchart TB
    classDef highlight fill:#00f,color:#fff
    room:MermaidGrotto(["room:MermaidGrotto"]):::highlight
    character:Aleria_Delamare -- in --> room:MermaidGrotto
    character:Rutger_Thorne -- in --> room:MermaidGrotto
    monster:AlannaTheMermaid -- in --> room:MermaidGrotto
    room:MermaidGrotto <--connectsVia--> doorPortal[[door:Portal32]]
    room:CthuluPool <--connectsVia--> doorPortal[[door:Portal32]]
    monster:AlannaTheMermaid -- owns --> treasure:TreasureChest5
    treasure:TreasureChest5 -- in --> room:MermaidGrotto
    character:Aleria_Delamare -- has --> spell:TrueSeeing

This is then rendered as follows:

---
title: Mermaid Grotto
---

flowchart TB
    classDef highlight fill:#00f,color:#fff
    room:MermaidGrotto(["room:MermaidGrotto"]):::highlight
    character:Aleria_Delamare -- in --> room:MermaidGrotto
    character:Rutger_Thorne -- in --> room:MermaidGrotto
    monster:AlannaTheMermaid -- in --> room:MermaidGrotto
    room:MermaidGrotto <--connectsVia--> doorPortal[[door:Portal32]]
    room:CthuluPool <--connectsVia--> doorPortal[[door:Portal32]]
    monster:AlannaTheMermaid -- owns --> treasure:TreasureChest5
    treasure:TreasureChest5 -- in --> room:MermaidGrotto
    character:Aleria_Delamare -- has --> spell:TrueSeeing
    
    

There are several significant advantages to using this approach compared to just using PNG or JPEG files. First, such diagrams are searchable using your browser page search box (which means that text can be copied). The output will flow to fill the container as much as possible, so you don’t end up with ultra-wide diagrams that extend well beyond the margin (the layout engine is HTML/CSS aware). Finally, it is possible to set up individual nodes as clickable regions that perform callbacks or bring up web content.

Class Diagrams

A related set of diagrams, Class Diagrams, are used to show the connections between specific classes of things, and likely are familiar to the reader when seen from the context of inheritance.

---
title: Animal example
---
classDiagram
    note "From Duck till Zebra"
    Animal <|-- Duck
    note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

The output of this description is similar to the above, and again can be customized with scripting and stylization.

---
title: Animal example
---
classDiagram
    note "From Duck till Zebra"
    Animal <|-- Duck
    note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

Other Diagram Modes and Possibilities

Beyond these, mermaid also includes support for UML entity relationship diagrams, mind maps, state diagrams, Gannt charts, swimland diagrams and user journey diagrams, with more likely under development. Additionally, mermaid.js supports a CLI for generating output as JPG, PNG, SVG and PDF formats, as well as a playground for testing features at https://mermaid.live/.

While domain specific languages like Mermaid are an obvious boon to blog writers and documentation maintainers, their real utility comes in that such diagrams can be dynamically generated very easily, making them ideal for generating images where data is likely to change frequently. Additionally, Mermaid scripts can be hashed as base64 encoded strings. For instance, the network graph above can be referenced through an image URL at mermaid.ink:

https://mermaid.ink/img/pako:eNqdU-tr2zAQ_1fM9csGTnDj-iXGYGvGPhXKavZhcSiHfYoEsi7IMl0X8r9PidMy1gfdZNmczr-HHqcdtNwRCGisNHzXKnQ-qj83NgqtNTgMS5KR0htlwusjqY0RZ0ki45YNO3EmpZzAjrkXV-R61N1Xx97zu1UDT7MNrN8LIR4lT1bBGFtPTnwy5DTeLslgj46i2SzSNnw_PuPwN_fb6DfkbmvFzr6F2bMdJk-0FmtFJ8wbqE_z0YfZrGVrqfXDd40Hcsfsrtl5NKvVIRbTIF2s13-oXHo1mvGa2fyPxGtr4Ds7HFfhHeEwOhL1KbhUNPhsUnjh5z_t_DOnpnDyHrYUaqZ2I90QabtpLMTQT2Kh8HYHqQa8op4aECHsSOJofBNqch-g47ZDT1867dmBkGgGigFHzzf3tgXhg_ADaKlx47B_RG3R_ghTfwCFIYgd_ARRVPMyS5O0KJLDk5Ux3IdsOb8osjRf5BfneZVVi30Mv478ZF7mVVqUi7wszkOvshjoOKOr6focb9H-N51sG8E?type=png

This generates the following PNG image:

As such, Mermaid is quietly entering into tool chains in the data architecture and semantic stacks, including in commercial products, and is becoming an integral part of tools such Atlassian Confluence, Github, and WordPress. Additionally, because mermaid can generate both static and SVG based diagrams, these can be fed into Microsoft Office products, reducing the need to spend a lot of time creating visualizations.

Let me know if articles such as this are interesting to you. by either commenting here or sending me a note to kurt.cagle@gmail.com (my Cagle Report email is coming soon), or by contacting me on LinkedIn at https://linkedin.com/in/kurtcagle or https://linkedin/com/company/the-cagle-report.