Let the LLM draw it: generating Mermaid diagrams with AI

I draw a lot of diagrams. Not because I love drawing, but because I integrate systems for a living, and the fastest way to understand a system is to see its shape. The problem with diagrams was always the same: the tool. You open some canvas app, you drag boxes, you fight the autolayout, and twenty minutes later you have a picture that goes out of date the moment you close the tab. I basically stopped making them.

Then I changed one thing. Instead of drawing, I describe, and an LLM writes the diagram as text. The format is Mermaid, and this combination quietly became one of my favorite uses of AI. No hype, just a real time saver.

What Mermaid actually is

Mermaid is a diagrams as code tool. You write a few lines of Markdown style text, and a renderer turns them into a diagram. That is the whole idea. A flowchart is just:

flowchart LR
    A[User] --> B{Auth?}
    B -->|yes| C[Dashboard]
    B -->|no| D[Login]
    D --> B

It covers most of what shows up in software docs: flowcharts, sequence diagrams, class diagrams, state machines, ER diagrams, plus Gantt charts, pie charts, user journeys, mindmaps and a few more. The first five are the ones I reach for daily.

The part that makes it stick: it renders almost everywhere developers already work. GitHub and GitLab render Mermaid natively in Markdown files, issues, pull requests and wikis. Notion, Obsidian and the VS Code Markdown preview do too. There is also a free Mermaid Live Editor in the browser for quick checks. You write text once, and it shows up as a real picture in the places your team already reads.

Why this is a perfect fit for an LLM

Here is the thing people miss. A model cannot draw. It cannot drag a box or nudge an arrow. But Mermaid is not drawing, it is writing, and writing structured text is exactly what an LLM is good at.

So the whole awkward part of diagramming, the manual layout, just disappears. I do not ask for a picture, I ask for text that becomes a picture. And that text has every property I want:

• The model can produce it directly. No plugin, no canvas, no special tool. It is just code in a code block.
• It lives in version control. A diagram in a .md file diffs cleanly in a pull request and never drifts out of sync with the repo it describes.
• It renders anywhere. Paste it into GitHub, a Notion page or your docs and it just shows up.
• It is editable. If one arrow is wrong, I fix one line. No clicking, no realigning the whole canvas.

How I actually use it

Two directions, and I use both constantly.

From a description, to think. When I am working out how a system should fit together, I talk it through with the model and ask for a Mermaid flowchart or sequence diagram of what we just discussed. Seeing it rendered immediately exposes the holes. An arrow pointing the wrong way, a missing error path, a box that does two jobs and should be two boxes. The diagram is not the deliverable here, it is a thinking tool that happens to be free now.

From existing code, to document. This is the bigger win. I point the model at a chunk of code, a route handler, a state machine, a set of database models, and ask it to produce the matching diagram. A sequence diagram from an API flow. An ER diagram from schema definitions. A state diagram from a status enum and its transitions. It is genuinely fast for getting a readable map of something I inherited or wrote months ago and half forgot.

One honest caveat: the model can get details wrong, especially on a big or messy codebase. So I treat the first output as a draft, not a source of truth. I read it against the code, fix the lines that are off, and only then commit it. The render step helps a lot here, because a wrong diagram usually looks wrong, which makes review fast.

Why I keep doing it

The real shift is not that AI draws pretty pictures. It is that the cost of a diagram dropped to almost nothing, so I make them when I would previously have skipped it. A quick sketch to align with a colleague. A diagram in a README so the next person does not have to reverse engineer the auth flow. A state machine I draw just to check my own thinking.

Diagrams as text were already a good idea. Pairing them with a model that writes text fluently is what finally made me do it by default. If you have been avoiding diagrams because the tools were annoying, the tool is not the obstacle anymore.