Mermaid: Diagrams as Code for People Who Hate Drawing

#tools#documentation#productivity

I’ve been using Mermaid a lot more at work lately, and honestly, it’s changed how I think about documentation. Not in some buzzwordy “digital transformation” way. Just… it removed the friction between “I have an idea for a diagram” and “there’s a diagram people can actually see.”

If you haven’t run into it yet, Mermaid lets you create diagrams using text. Not drag-and-drop boxes. Not a proprietary file format. Just plain text that looks vaguely like Markdown, rendered into SVG diagrams in your browser.

That’s it. That’s the whole pitch. And once you’ve used it, everything else feels archaic.

Why I’m Sold

It Lives in Your Code

Mermaid diagrams are just text blocks. You put them in Markdown files, commit them to git, diff them in pull requests, review them like code. No binary blobs. No “which version of Visio did you use?” No emailing PNGs back and forth.

Mermaid editor

The diagram is the source. Not an export of the source. If you need to change an arrow, you change a line of text. Your version control actually works the way it’s supposed to.

It’s Everywhere

This is the part that surprised me. Mermaid isn’t some niche tool. It’s baked into things you probably already use:

Mermaid editor

That panel above? It’s a live Mermaid editor, running entirely on this site. No third-party embeds, no accounts, no ads. Type on the left, watch the diagram render on the right. It’s how I prototype most of my diagrams before committing them.

LLMs Speak Mermaid

This is where it gets fun. Because Mermaid is just text with a predictable structure, LLMs are shockingly good at generating it. Ask an LLM to “draw me a sequence diagram of a user logging in” and you’ll get valid Mermaid syntax back.

Mermaid editor

I’m not saying you should let AI write all your architecture docs. But when you need a quick diagram and you’re too lazy to remember the exact syntax? Ask the robot. It usually gets it right on the first try.

There are even MCP servers and plugins specifically for generating Mermaid diagrams with AI. The ecosystem is growing fast.

Who Owns This Thing?

Good question. Mermaid is MIT licensed, completely open source. It’s not owned by some corporation trying to lock you into a platform. It was created by Knut Sveidqvist back in 2014, and it’s maintained by a community of contributors on GitHub.

There’s a company called Mermaid Chart that offers paid features (team collaboration, version history, etc.), but the core library is free and always will be. You can self-host it, embed it, modify it, whatever. The spec is public, the renderer is public, there’s no vendor lock-in.

That matters to me. I’ve been burned by proprietary web diagramming tools before. You spend years building up workflows, only for access to vanish when someone leaves the company or a teammate without an active seat can’t even open the file.

Mermaid doesn’t do that. It’s plain text, and text never goes out of style. It can live in a git repo with full version history, sit in an Obsidian vault for personal reference, or drop straight into a Jira comment for quick context down the road.

What Can You Actually Draw?

A lot, it turns out. Here are the ones I use most:

Flowcharts

The bread and butter. Decision trees, process flows, state machines.

Mermaid editor

Sequence Diagrams

Perfect for API calls, message flows, anything with back-and-forth between components.

Mermaid editor

Gantt Charts

Project timelines. I use these in planning docs more than I expected to.

Mermaid editor

Class Diagrams

For when you need to show object relationships without drawing UML by hand.

Mermaid editor

There are more. Pie charts, ER diagrams, state diagrams, mind maps, even git branch visualizations. The docs have the full list with examples.

How to Get Started

The fastest way is the editor at the top of this post. It’s a split pane with the code on the left and the rendered diagram on the right. Play with it, break it, see what works. When you’re ready to share a diagram, the Mermaid Live Editor is the same idea as a hosted app.

Once you’re comfortable, try putting a Mermaid block in a GitHub issue or a README. GitHub renders it automatically. No plugins, no setup.

```mermaid
graph TD
    A[You] --> B[Write some text]
    B --> C[GitHub renders it]
```

If you use Obsidian, it’s built in. Just add a mermaid code block and it renders in preview mode. VS Code has the “Markdown Preview Mermaid Support” extension that does the same thing.

For the enterprise tools (Jira, Confluence), check your marketplace. There are usually free or cheap plugins that add Mermaid support. Once your team sees how easy it is, they’ll start using it too.

The Full Circle

Here’s what I like most: Mermaid closes the loop between thinking and documenting. When I’m sketching out a system design, I don’t need to switch to a drawing tool. I just type. The diagram appears. I commit it. Someone reviews it. We merge it.

Six months later, when someone asks “why does this work this way?”, the diagram is still there. In the repo. In the docs. Rendered on GitHub. Not lost in some Slack thread or buried in a PowerPoint nobody opens anymore.

It’s not revolutionary. It’s just… good. Text-based, open source, everywhere you need it. What more do you want from a tool?

That’s it. Go draw something.