--- title: "Mermaid: Diagrams as Code for People Who Hate Drawing" description: "Why I've been using Mermaid for everything at work, and why you should too." date: 2026-08-11T00:00:00.000Z tags: ["tools", "documentation", "productivity"] canonical: https://nick.rivett.dev/posts/mermaid-diagrams-as-code/ --- # Mermaid: Diagrams as Code for People Who Hate Drawing 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 graph LR A[dev.mmd] --> B{git commit} B --> C[PR review] C --> D[merged] ``` 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: - **GitHub** renders Mermaid in Markdown files and issues natively - **GitLab** does the same - **Azure DevOps** wikis support it - **Obsidian** has it built in - **VS Code** has a dozen plugins for preview and export - **Jira** and **Confluence** have multiple plugins (Atlassian's marketplace is flooded with them) - **Notion** supports it in code blocks - **JetBrains IDEs** have official plugins ```mermaid graph TD A[Idea] --> B[Write some text] B --> C[Diagram appears] C --> D[Commit to git] ``` 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 sequenceDiagram participant U as User participant B as Browser participant S as Server U->>B: Enter credentials B->>S: POST /login S-->>B: JWT token B->>U: Redirect to dashboard ``` 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 graph TD A[Start] --> B{Is it broken?} B -->|Yes| C[Fix it] B -->|No| D[Ship it] C --> D ``` ### Sequence Diagrams Perfect for API calls, message flows, anything with back-and-forth between components. ```mermaid sequenceDiagram participant C as Client participant S as Server participant D as Database C->>S: GET /api/users S->>D: SELECT * FROM users D-->>S: rows S-->>C: JSON response ``` ### Gantt Charts Project timelines. I use these in planning docs more than I expected to. ```mermaid gantt title Project Timeline dateFormat YYYY-MM-DD section Design Wireframes :a1, 2026-08-01, 7d Mockups :a2, after a1, 5d section Build Frontend :b1, after a2, 14d Backend :b2, after a2, 14d section Launch Testing :c1, after b1, 7d Deploy :c2, after c1, 2d ``` ### Class Diagrams For when you need to show object relationships without drawing UML by hand. ```mermaid classDiagram class Animal { +String name +int age +makeSound() } class Dog { +String breed +fetch() } Animal <|-- Dog ``` 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](https://mermaid.live/) 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? ## Links to Play With - **[Mermaid Live Editor](https://mermaid.live/)** - Try it right now - **[Mermaid Docs](https://mermaid.js.org/)** - Full syntax reference - **[GitHub's Mermaid Guide](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/)** - How GitHub renders it - **[Community Integrations](https://mermaid.js.org/ecosystem/integrations-community.html)** - See what tools support it That's it. Go draw something.