I love diagram languages like mermaid.js and PlantUML because the text format that backs the diagram can be tweaked, takes up very little space in storage, and can be re-rendered at various resolutions any time you need. They’re great! I hate writing them. Mermaid has a different syntax for every diagram type, and they’re hard to remember. PlantUML is more consistent, though not totally, and in my experience can be quite verbose.

I use drawing tools to make diagrams for presentations. I’ve gotten pretty good at Excalidraw. I like that I have total control over the layout, which is difficult for me to get with diagram languages. They stink for documentation. The images look good, but need to be rendered at multiple resolutions. You need to save the file somewhere to make edits. Nodes get disconnected accidentally all the time.

What I want is to draw the diagram by hand - the fastest way. Then I want it digitized into a format I can tweak. We’ve been trying to do that for ages with digital whiteboards, etc. It’s “eh”.

I’ve been incorporating LLMs more and more into my software development process in the last month or so. The Claude CLI and Cursor have both been working well for me. I’ve done a lot of the “normal” software dev stuff: have an agent write up and revise benchmark tests, write a CRUD API for a new type I’m introducing.

So I decided to see how good it would be at making Mermaid diagrams for me. I drew this diagram on paper, snapped a photo and dropped it onto my laptop.

sketch

Here’s the prompt I gave the Claude CLI:

Turn the IMG_ file in this folder into a mermaid diagram in the .mmd format. It should be either a flowchart or a box diagram

Claude can’t read HEIC, so it even converted the image to a JPEG first with sips.

After that I used mermaid-cli to render a PNG and opened it in Chrome:

$ npx @mermaid-js/mermaid-cli -i file.mmd && open file.mmd.svg

Here’s the first output:

generated

Pretty good!

I’ve used this at work too, for box diagrams with around 20 elements, and it’s done pretty well. I get the diagram I want after two or three rounds of tweaking. The feedback loop is really fast and less error prone than the mermaid live editor. I think I cut a diagram drawing session about in half, because my hand-drawn diagram turns into text so quickly.