Beyond Mermaid: Comparing Markdown Diagram-as-Code Tools
Quick summary
Mermaid is the diagram tool most developers meet first, mostly because GitHub renders it for free. But it's not the only option, and it's not always the right one. If you've outgrown Mermaid's layout control, or you need a diagram type it doesn't cover, D2, PlantUML, and Graphviz/DOT are the markdown diagram tools worth knowing. Each one makes a genuinely different trade-off. Haven't tried text-based diagrams yet? Adding Mermaid diagrams to your Markdown files is still the easiest place to start. Below are six diagram-as-code tools, what each is actually good at, and how to pick between them.
Why diagram-as-code beats a GUI diagram tool
The pitch for diagram-as-code is simple: the diagram's source is a plain text file, not a proprietary binary format locked inside a desktop app. That text file lives next to the code or notes it describes, so it diffs cleanly in git, survives a laptop swap, and never turns into an orphaned .drawio file nobody remembers how to open. Mermaid was built around exactly this problem. Its creator, Knut Sveidqvist, started the project in 2014 after losing a diagram stored in a proprietary Visio file, and designed it specifically to keep diagrams versioned alongside the code they document. The same logic extends to how you manage code snippets in plain Markdown files instead of a format-locked snippet manager.
The trade-off is real, though. A layout engine, not you, decides where each node lands, so you give up the pixel-level control a design tool gives you. For a one-off polished diagram meant for a slide deck, a GUI tool is still the better call. But for a diagram that needs to stay accurate as the system it describes changes, text wins.
The list: six diagram-as-code tools worth knowing
1. Mermaid — the zero-setup default
Mermaid's biggest advantage isn't its syntax — it's where it renders. GitHub renders Mermaid natively in Markdown files, Issues, pull requests, and wikis. Fence a code block with mermaid and it just appears: no build step, no plugin. GitLab and several other note-taking apps support it too. It covers six diagram types — flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, and entity-relationship diagrams — which is plenty for most day-to-day documentation. That zero-setup rendering is why it's the default.
2. D2 — the developer-first newcomer
D2 stands for "Declarative Diagramming": you describe the relationships, and the tool generates the image. It ships with a CLI, a watch mode for live preview while you edit, and a choice of three layout engines (dagre, elk, and tala) so you can tune how a complex diagram gets arranged. The catch: unlike Mermaid, no major platform renders D2 natively yet, so you need to run the CLI or an external renderer and embed the resulting image. It's worth the extra step if you want more layout control than Mermaid gives you and don't mind a build step.
3. PlantUML — the UML generalist
Where Mermaid covers six diagram types, PlantUML covers UML diagrams plus Archimate, block diagrams, BPMN, C4 models, ERD, Gantt charts, mind maps, and work breakdown structures — it can even visualize raw JSON and YAML. It's been around since 2009, longer than Mermaid, and uses its own domain-specific language rather than trying to look like Markdown. Under the hood, it hands its layout work to Graphviz. If your documentation needs UML specifically, or a diagram type Mermaid doesn't have, this is the broader tool.
4. Graphviz / DOT — the substrate underneath
Graphviz predates every tool on this list — it came out of AT&T Labs Research before 1991. It reads graphs written in the DOT language and lays them out using proven, decades-old algorithms, which is exactly why PlantUML uses it as a layout engine instead of writing its own. Graphviz is the right tool when the diagram is really a graph problem: a large dependency tree, a call graph, a network topology. Doxygen and Sphinx generate diagrams through it automatically, and Terraform can output its execution plans in DOT format for the same reason. The trade-off is aesthetics: Graphviz optimizes for correct layout over a polished look.
5. Kroki — the one-API wrapper
Kroki doesn't compete with the tools above so much as sit in front of them. It exposes a single REST API that can render Mermaid, PlantUML, Graphviz, and several other diagram languages from plain text, returning SVG, PNG, or PDF. That's handy when you'd rather send text to an endpoint and get an image back than install and maintain multiple local renderers.
6. Structurizr DSL — the architecture-diagram specialist
Structurizr DSL is narrower than everything else here, on purpose. It's built around the C4 model for describing software architecture, and it generates several levels of abstraction — context, containers, components — from a single model instead of you drawing each view by hand. That discipline is exactly what makes it useful for architecture documentation, and exactly why it's a poor fit for a quick flowchart. The learning curve only pays off if you're maintaining architecture diagrams long-term.
Putting this into practice with Carets
Whichever tool you pick, the diagram's source is still just a fenced code block — a mermaid, d2, plantuml, or dot snippet sitting inside a Markdown file. That's exactly the kind of file Carets is built to edit: a native notes and code editor for iPhone, iPad, and Mac that handles Markdown, plain text, and code with syntax highlighting, organized into files, projects, and tags. Drafting a diagram block on your iPad on the way into a standup, or keeping the DOT source for an architecture diagram next to its README notes — labeling fenced code blocks so you can find them later matters more than which diagramming syntax you picked. Your diagram source stays a plain text file: portable, searchable, and readable in five years regardless of which renderer is fashionable by then. Carets is available on the App Store for iPhone, iPad, and Mac.
Frequently Asked Questions
What does "diagram-as-code" actually mean?
It means describing a diagram's nodes and relationships in a plain text syntax instead of dragging shapes around a canvas. The text lives in a file you can version, diff, and search — the diagram is just a rendering of that file, not the source of truth itself.
Is D2 meant to replace Mermaid?
Not exactly — they solve overlapping but different problems. Mermaid's advantage is that GitHub, GitLab, and several note apps render it natively with zero setup. D2 has more layout control and multiple layout engines, but you need a build step or an external renderer to see the result, since it isn't natively supported inside Markdown viewers the way Mermaid is.
Can I drop a PlantUML or Graphviz diagram straight into GitHub Markdown?
No — GitHub's native fenced-code-block rendering currently covers Mermaid, GeoJSON/TopoJSON, and ASCII STL. PlantUML and Graphviz/DOT diagrams need to be rendered externally, or through a conversion step like Pandoc's diagram filter, into an image, then embedded as that image.
Which one should I actually start with?
If the diagram lives in a GitHub README, issue, or pull request, start with Mermaid — it renders with no setup. If you're documenting UML, C4, or enterprise architecture with more diagram types than Mermaid covers, PlantUML is the broader tool. If you want more layout control for a diagram you'll render and embed as an image, D2 is worth the extra step.
Do I need to be a developer to use these?
No. The syntax is closer to a short list of rules than a programming language, and most of these tools have a live web editor where you can paste text and see the diagram update instantly — no local install required to just try one out.
Conclusion
There's no single best diagram-as-code tool, because "best" depends on where the diagram gets read. Mermaid wins when the diagram lives in GitHub. PlantUML wins when you need UML or C4 breadth. Graphviz wins when the diagram is really a dependency graph. D2 and Structurizr DSL both trade setup effort for more control, just in different directions. What all of them share is the part actually worth keeping: the diagram's source is a plain text file, so it stays editable, searchable, and yours no matter which renderer is fashionable next year.