36 lines
1.7 KiB
Markdown
36 lines
1.7 KiB
Markdown
|
---
|
||
|
|
title: Mermaid - markdown for charts
|
||
|
|
date: 2024-08-18
|
||
|
|
permalink: daily/2024/08/18/mermaid-markdown-for-charts
|
||
|
|
tags:
|
||
|
|
- software-development
|
||
|
|
- documentation
|
||
|
|
cta: ~
|
||
|
|
snippet: |
|
||
|
|
Mermaid is a nice way to generate and store diagrams within your projects.
|
||
|
|
---
|
||
|
|
|
||
|
|
[Whilst mentoring at the School of Code Hackathon][0], 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][1] 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][2], 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][3], which I recently open-sourced, and that GitHub renders by default (you can click the 'Code' tab to see the code for the chart).
|
||
|
|
|
||
|
|
[0]: {{site.url}}/daily/2024/08/16/what-are-err--req-and-res
|
||
|
|
[1]: {{site.url}}/archive/2022/09/23/adrs-technical-design-documents
|
||
|
|
[2]: https://github.com/mermaid-js/mermaid
|
||
|
|
[3]: https://github.com/opdavies/build-configs/blob/f02fce7ff5b5cff202ec8b893a4b3c7e7c56f3c4/docs/diagram.mmd
|