Earlier, I wrote about rendering Mermaid graphs in Markdown on GitHub by invoking a script, possibly using a make target to cover all Markdown files in an entire repository. Since then I’ve used Mermaid diagrams and the script presented in that post in README.md docs for a couple of projects. While the script works great, having to remember to run it or plumb client side automation to do so automatically can be a bit of a hassle.
I had been toying with the idea of putting the script up in a GitHub repository, for easy inclusion as a git submodule, and then realized that turning that into a GitHub Action would be even easier. So, that’s what I did.
GitHub Actions
GitHub Actions, if you’re new to the term, is GitHub’s workflow system for build automation, continuous integration, or whatever other task you might want to perform in reaction to repository changes. Think of an Action as a small program. Actions are the building blocks of workflows. A few Actions put together in a workflow operate in the same execution environment and have access to the same file system that usually contained a fresh checkout of your repository. Actions combined in a workflow can build your code, run your tests, deploy to staging or production, generate static html and publish your website and now also render Mermaid diagrams in Markdown files.
render-md-mermaid
The Action I built, render-md-mermaid, can be used in any GitHub repository. Put it in a workflow, together with checkout and git-auto-commit and it will automatically render any Mermaid diagram in any Markdown file (if formatted correctly) wherever it runs.
To install it in your repo, add the following yaml configuration to .github/workflows/render-md-mermaid.yml.
name: render-md-mermaid
on: push
jobs:
render-md-mermaid:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Render images for every Mermaid diagram in all Markdown files (*.md) in the repo
uses: nielsvaneck/render-md-mermaid@v2
- name: Commit rendered png and svg files
uses: stefanzweifel/git-auto-commit-action@v4
with:
file_pattern: "*[.svg,.png]"
commit_message: automatically rendered mermaid diagrams
This workflow uses GitHub’s checkout action to get the latest copy of your repository, then runs render-md-mermaid on it and finally commits any .svg or .png files that were generated in the process back to the repository.
Under the hood
The render-md-mermaid Action is built using the mermaid-cli Docker image. I had to make some small tweaks to the way the mermaid client is invoked, but the render-md-mermaid.sh script that does the heavy lifting is able to run stand-alone and in-container.
In the end, the biggest hurdle I ran into was figuring out the correct file_pattern parameter to git-auto-commit. Even though the script should only create image files, I wanted to make sure nothing else gets comitted by accident.
I found the documented examples did not work for my use case where you may have a .svg file but not a .png or vice versa. Ultimately, I found that "*[.svg,.png]" –in double quotes because it starts with a *, a special character in YAML– matches any .svg or .png file that may show up in git status as a result of diagram generation.
Plans
My goal is to add some bats tests and if the Action gets some usage, I may play around with ways to pass a stylesheet and configuration to the Mermaid renderer.
For now, I hope this is useful to someone. If so, or if you have suggestions, shoot me a note!