Jump to the navigation menu

Mermaid - markdown for charts

Whilst mentoring at the School of Code Hackathon, something the team and I discussed was documentation and documenting any decisions we made about the approaches they were taking, the techologies to use, etc.

We kept it simple by adding this to a README file, but I also mentioned ADRs and technical decision documents and how they can be written in Markdown and stored alongside the code in the same repository.

Another approach to documentation that I like is to create diagrams and flow charts.

I've used various tools to do this, but recently, I've started to use Mermaid, which is a Markdown-like syntax to generate charts and diagrams.

Here's the thing

There are online tools to do this, but there's also mmdc command-line tool that generates diagrams locally.

This means that I can easily generate diagrams and store in the codebase too, and have them version-controlled so I can see the history as they evolve during the project.

Want an example?

Here's one I did for the Build Configs tool, which I recently open-sourced, and that GitHub renders by default (you can click the 'Code' tab to see the code for the chart).

- Oliver

Was this interesting?

Sign up here and get more like this delivered straight to your inbox every day.

About me

Picture of Oliver

I'm an certified Drupal Triple Expert with 18 years of experience, a Drupal core contributor, public speaker, live streamer, and host of the Beyond Blocks podcast.