Using Mermaid JS for Insanely Quick Diagramming
Somehow I have only just head about Mermaid!
As someone who creates a lot of diagrams in ‘infinite canvas’ tools such as Figma or Freeform I am finding Mermaid a nice tool to get ideas down even faster, so I’ve put together this article with some examples in the hope you’ll find it just as useful.
What is Mermaid?
Mermaid is a JavaScript based framework for creating diagrams with plain text.
Type out the steps for your flow chart in the correct plain text format, and a diagram based on what you entered will be generated as you do so. Sounds simple, and it is.
At its most basic creating a flow using Mermaid looks something like the following:
1 {Step One} --> 2{Step Two} --> 3{Step Three} --> 4{Step Four} --> 5{Step Five}
And being plain text means it’s even more awesome because it’s transportable.
There’s multiple apps that can “read” Mermaid syntax and those are what generate the diagrams - the ones I have used are Notion and GitHub, and Visual Studio Code or Confluence also generate diagrams from Mermaid with a plugin. A full list is available on the Mermaid site, and there’s also a playground on there too meaning you can try it out live.
Within Notion Mermaid looks like the following, with the code on top and the diagram below:
Use Cases
Mermaid is not for situations when you need an extensive diagram, or tons of control around placement and spacing etc.
I find Mermaid best for getting things into a diagram format quickly, to highlight points or kick off a bigger piece of work. Whenever I need to highlight a point, I’ll just copy and paste from my templates and I’ve got a useful graph in literally a couple of minutes.
The Mermaid Syntax
The syntax itself is pretty simple, so rather than try to explain it I’ve put together a few examples below you can copy and paste. I’ve included some basic styling too and there’s tons more styling options here - but in the spirit of keeping things simple I haven’t used many styles.
My favourite part of the syntax is being able to change the direction of flowcharts just by switching out LR (left right) for TB (top to bottom), BT (bottom to top) or RL (right left). Gloriously simple as text should be.
Examples
Let’s take a look at some common examples of where I’ve found it most useful. You can copy and paste the code directly from GitHub and edit for your own purposes.
A Basic Sitemap
Like I say Mermaid probably isn't the best solution for you to be creating a full sitemap with, but it's great for getting something simple approved in a meeting or highlighting the benefits of structure change.
Page Types vs Search Intent
Something I find I’m constantly explaining to non-SEOs is search intent, and I’ve been finding this format useful to demonstrate customer types vs search terms and the content that satisfies the search intent.
Illustrating Conversion Tagging
This constantly comes up when there’s a conversion process to run through, and highlighting the various steps from a reporting point of view can be very useful. The thing I like about this one is you can complete the ‘visible flow’ part then work on the analytics events afterwards.
