Make useful diagrams for your technical documentation

Our favourite tools for making diagrams are Excalidraw and Mermaid. Excalidraw is useful for its flexibility. Most people enjoy the hand-drawn aesthetic, and it also frees you from having to spend time making sure every pixel is perfectly aligned, as the ‘rough’ look is part of the aesthetic.

Mermaid is useful because diagrams are stored as text, so they are version controlled, automatically optimized, and everything is integrated into your existing flow.

Here’s an example of an Excalidraw diagram.

Setting up Mermaid is a bit more involved. You’ll need to install some extra libraries, configure it in your Astro configuration file, and probably tweak your CSS to make the diagrams look nice, stop the text from overflowing and various other bugs you might encounter.

Check back soon for a detailed guide on the best way to configure mermaid and Astro starlight!