¬ just serendipity 🍀 (not just serendipity)

When writing documentation in markdown e.g. for projects stored in git, adding a system architecture or design diagram is a great way to boost its readability, especially to unfamiliar readers.

My favorite way to generate diagrams is with GraphViz. It is widely available and easy to use.

That said, MermaidJS has native integration with GitHub and GitLab circa 2 years ago, and that’s hard to beat. Graphviz, sadly, does not.

There is a live editor for quick prototyping and iteration: https://mermaid.live/

Once you are happy with the result, you can easily embed it in markdown¹:

```mermaid
flowchart TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
C -->|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
```

…and it will get automatically rendered in the aforementioned git forges.

MermaidJS is quite intuitive to use. There is plenty of documentation for it², e.g. for graphs / flowcharts: https://mermaid.js.org/syntax/flowchart.html.