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?
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:
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!