I've been doing a lot of writing recently.

Not blog writing, of course, but writing for work.

Security and cloud topics being what they are, reading paragraph after paragraph can get a bit much.

I try to break things up with external references, and the occasional images and videos.

This week I tried to add something trivially simple - a generated diagram. Little did I know how much of a yak shaving exercise that would turn out to be.

Getting the picture

A good picture is easily worth a thousand words.

A good cloud infrastructure/network/auth flow diagram is a great visual aid that's far easier to comprehend than a page of text.

The typical tools are the usual suspects, Visio, Omnigraffle, Dia, even PowerPoint can be the tool of choice.

I felt that none of those were suitable in my case.

All of those tools are specifically WYSIWYG, what you see is what you get, or, to put another way, the diagrams require manual dragging and linking. That's all fine if the priority is to have fine control over object positions - probably a valid use case for PowerPoint designs.

In my case that's not a priority - rather, the goal is purely to display the flow, let the diagram generator itself figure out the perfect alignment, and have "diagram as code".

Mermaid

I already use Markdown, and Mermaid diagrams fit well within this workflow.

Mermaid, like Markdown, provides a very simple syntax, in plain text (e.g. A --> B).

In something like Github, it's already supported out of the box, as the docs illustrate.

Sadly I'm not writing for Github repo content, so I need to see the image and export it, locally.

Getting a Preview

Like Markdown, Mermaid is a JS/CSS tech so we should be able to get it into HTML & other formats.

As a first step, the common use case is to see the result locally.

Going with the simplest option - a VSCode clone provides Markdown Preview support and an extension (Markdown Preview Mermaid Support) can add Mermaid support as well.

Other editors may have their own options.

File, please

In-editor preview is wonderful but it isn't the final output.

We need the actual rendered file, PNG, SVG, or otherwise.

This is where the fun begins.

Extensions, extensions

Going with the idea that I just want to export what I already can see, the next logical step is to find an extension that can do so.

Searching for a suitable extension yields the following:

ExportMermaid2File

Installs fine - crashes on use with a Module Not Found.

Mermaid Export

Installs fine - crashed on use with "The system cannot find the path specified."

Checking Github reveals issues are open.

At this point I am convinced that while I may be able to sink some time into troubleshooting extensions, this is not the best way forward.

Curiouser and curiouser

Given that I might want to use another editor (like, Zed), and given that extensions so far haven't been suitable, it may be best to go to with the mermaid-cli and avoid the dependency clashes.

Mermaid docs helpfully document the install process: NPM, or Docker.

Docker is obviously overkill for a local one-liner, so I run the NPM install.

It crashes on first run:

Error: Could not find Chrome

Oh dear.

I am pretty sure Chrome is installed.

Like the extension issues, this is probably fixable, but I get the idea that maybe, given the headless use case, the Docker approach could actually be easier due to perhaps being a bit more debugged.

Let's use Docker. It's already installed of course.

It crashes immediately.

Yak Shaving

To summarise, at this stage I would like to fix my Docker install, so I can run a Docker container, with mermaid-cli, so I can generate the image of the diagram I have in code.

That does seem somewhat overkill, however at this point, I already have a broken Docker setup and that will need to be fixed sooner or later.

Re-attempting to launch it returns the same error, so at least it is consistent.

com.docker.virtualization: process terminated unexpectedly: use of closed network connection

Having a look, yields this Github thread and suggests one possible solution - deleting Docker data file.

While not suitable in all cases, the above actually worked.

Docker's online.

docker pull minlag/mermaid-cli
# works!

docker run --rm -u `id -u`:`id -g` -v ./diagrams:/data minlag/mermaid-cli -i flowchart.md
# works, creates SVG

docker run --rm -u `id -u`:`id -g` -v ./diagrams:/data minlag/mermaid-cli -i flowchart.md -o flowchart.png -b transparent
# works, creates PNG as specified

Closing Thoughts

It's amusing that something as simple as creating a diagram from code could actually lead to a sudden troubleshooting experience.

It has however led to interesting realisations:

• Mermaid is good
• Sometimes, Docker is by far the easiest solution