Scroll the menu to find all the places to visit
Mermaid Publishing Tip
23 Oct 2021Mermaid is a popular web-based diagramming tool that allows you to generate a variety of visualisations based on sets of text instructions that tell Mermaid how to generate the diagram. I’ve been using it for a little while to generate relatively simple flow diagrams that I need to build out iteratively or require regular updates. This is because once I have the structure in place it is often much quicker for me to add an instruction to change such a diagram than it is for me to rework a diagram in a visual editor.
I recently used some Mermaid generated diagrams in a post on this site, and I’m going to share a tip for a challenge I encountered.
In my Automating your Obsidian Workspace post, I used Mermaid diagrams for a couple of illustrations as to how the automation flow was being put together. I created the Mermaid instructions to generate the diagrams and then used the online Mermaid editor to generate image files to be included in the post.
What I also wanted to do was to keep the text instructions available too within the Markdown file that I wrote the post in and is processed (by Jekyll) to create the final web page.
My first thought was to place the instructions between HTML comment tags:
<!--
*** Put the Mermaid Instructions Here ***
-->
That would then hide the content from being published. Unfortunately some of the Mermaid notation used for links between nodes in a diagram are exactly the same as a closing HTML comment tag. Even keeping the Mermaid code inside a code block, this sort of text …
<!--
```
CP --> QA --> QM --> B --> C --> D
```
-->
… shows up like this …
QA –> QM –> B –> C –> D </pre></code> –>
… rather than being entirely hidden.
Obviously HTML comment tags were not going to be a viable option. Fortunately there is more than one way to hide content in a web page. The approach I settled on was to use a division set to not display any content.
<div style="display: none;">
*** Put the Mermaid Instructions Here ***
</div>
This is one of the flow diagram’s from the post.
Here is the content I therefore keep next to the image link in my Markdown file.
<div style="display: none;">
## Mermaid Code to generate this diagram
```
graph LR
subgraph 1[ ]
CP([Command Palette])
subgraph 2[Quick Add]
QA(Quick Addition)
QM(Macro)
end
B[Call Script]
C[Open URI]
D[Load Workspace]
CP --> QA --> QM --> B --> C --> D
end
style 2 fill:#c1cfc0,stroke:#87A8A4,stroke-width:2px
```
</div>I can just copy and paste the Mermaid instructions into the online editor any time I want to modify it and generate a new image. Then I just copy back the modified instructions to my source Markdown and everything is there should I need to apply any updates. It saves me having to keep separate generation documentation, or having to build it from scratch each time.
That’s my little tip, and if you have not yet given Mermaid a try, you really should. It is a great tool for flow diagrams in particular.
