I went down the rabbit hole to look at the Mermaid diagram tool that allows you to generate graphs and charts of various kinds using a markdown-like syntax. A number of markdown systems support Mermaid now without additional tooling, including GitHub. Jekyll, which powers this site, also has a Mermaid plugin, and it seems like it might be useful at some point, so I decided to experiment, because what else was I going to do with my time?

mainwrite-blog-post-on-freebsdreinstall-freebsdinstall-nvim-markdown-pluginwrite-blog-post-about-nvim-pluginstweak-blog-settingsplay-with-mermaidNeed a projectPlay with FreeBSD againStart writing markdownGet FreeBSD reinstalledWrite more markdownSpend 4 hours trying to get it workingWrite a post to save others from my fateFix formatting and other shitHere we are
GitHub repo graph showing how my focus jumps between current projects, like experimenting with FreeBSD and making superfluous updates to this site


The mermaid markdown (mmd) for this graph:

gitGraph
   commit id: "Need a project"
   commit id: "Play with FreeBSD again"
   branch write-blog-post-on-freebsd
   checkout write-blog-post-on-freebsd
   commit id: "Start writing markdown"
   branch reinstall-freebsd
   checkout reinstall-freebsd
   commit id: "Get FreeBSD reinstalled"
   checkout write-blog-post-on-freebsd
   merge reinstall-freebsd
   commit id: "Write more markdown"
   branch install-nvim-markdown-plugin
   checkout install-nvim-markdown-plugin
   commit id: "Spend 4 hours trying to get it working"
   branch write-blog-post-about-nvim-plugins
   checkout write-blog-post-about-nvim-plugins
   commit id: "Write a post to save others from my fate"
   checkout install-nvim-markdown-plugin
   merge write-blog-post-about-nvim-plugins
   checkout write-blog-post-on-freebsd
   merge install-nvim-markdown-plugin
   branch tweak-blog-settings
   checkout tweak-blog-settings
   commit id: "Fix formatting and other shit"
   checkout write-blog-post-on-freebsd
   merge tweak-blog-settings
   branch play-with-mermaid
   checkout play-with-mermaid
   commit id: "Here we are"


To embed in an .md file, you can wrap it like this:

```mermaid
gitGraph
   commit id: "Need a project"
   commit id: "Play with FreeBSD again"
   branch write-blog-post-on-freebsd
   checkout write-blog-post-on-freebsd
   commit id: "Start writing markdown"
   branch reinstall-freebsd
   checkout reinstall-freebsd
   commit id: "Get FreeBSD reinstalled"
   checkout write-blog-post-on-freebsd
   merge reinstall-freebsd
   commit id: "Write more markdown"
   branch install-nvim-markdown-plugin
   checkout install-nvim-markdown-plugin
   commit id: "Spend 4 hours trying to get it working"
   branch write-blog-post-about-nvim-plugins
   checkout write-blog-post-about-nvim-plugins
   commit id: "Write a post to save others from my fate"
   checkout install-nvim-markdown-plugin
   merge write-blog-post-about-nvim-plugins
   checkout write-blog-post-on-freebsd
   merge install-nvim-markdown-plugin
   branch tweak-blog-settings
   checkout tweak-blog-settings
   commit id: "Fix formatting and other shit"
   checkout write-blog-post-on-freebsd
   merge tweak-blog-settings
   branch play-with-mermaid
   checkout play-with-mermaid
   commit id: "Here we are"
```

Rendering to a file

You can use the cli to write directly to a file. You can install the cli as an npm package locally, but I got dependency errors and I’m not a node person, so forget that.

Fortunately, they distribute a docker container. If you already have docker installed, you just need to pull the image, and you’re good to go.

The cli supports svg, png, md, and pdf output formats. I want an image file, so first I tried png but the file wasn’t loadable in one image viewer I tried. Instead I output to svg and then used gimp to convert it to png. (Plenty of other tools exist for that image conversion.)

k@slaapmatje:~$ mkdir mermaid
k@slaapmatje:~$ mv my-brain.mmd mermaid
k@slaapmatje:~$ cd mermaid
k@slaapmatje:~/mermaid$ chmod 777 .
k@slaapmatje:~/mermaid$ sudo docker pull minlag/mermaid-cli
Using default tag: latest
latest: Pulling from minlag/mermaid-cli
Digest: sha256:bf130e7ce53fa2269d4d7784c4d7d3edea63185f2fb72d337148224ffd22f1ec
Status: Image is up to date for minlag/mermaid-cli:latest
docker.io/minlag/mermaid-cli:latest
k@slaapmatje:~/mermaid$ sudo docker run -it -v `pwd`:/data minlag/mermaid-cli -i /data/my-brain.mmd -o /data/my-brain.svg
Generating single mermaid chart
k@slaapmatje:~/mermaid$ ls
my-brain.mmd  my-brain.svg
k@slaapmatje:~/mermaid$

(We give the mermaid directory global write permissions so the docker user can write to it.)


Mermaid supports a number of graph and diagram formats, and it’s fun to write!