Ask ten teams how they draw diagrams and you will hear one name: Mermaid. It is the default answer to "diagrams as code." But "what are the Mermaid alternatives" is the wrong first question. The right one is more mundane: after the diagram is drawn, where does it go?
Does it live in the repository, changing three times a sprint, reviewed line by line in pull requests? Does it live on a whiteboard during a design review, warm for an hour and forgotten by Friday? Or does it appear on a marketing page, an investor deck, a launch keynote — speaking for your product before you do?
Three destinations, three very different tools, three very different ways of working.
Some context first. On September 15 this site published a comparison of AI diagram tools titled "Who Owns the Diagram After It Is Generated," covering five projects — diagram-design, Mermaid, Excalidraw, D2, and PlantUML — around a single question: once a diagram is generated, who owns it, and in what form does it persist? This article asks a different one: given where the diagram ends up — a git diff, a collaborative whiteboard, a published deck — which route should you take? We also pull draw.io into the comparison, completing four routes. The two articles approach the same landscape from different angles.
So who are the four routes? mermaid-js/mermaid — repo: github.com/mermaid-js/mermaid — the flagship of diagram-as-code: text in, diagram out, diagrams travel with the code. jgraph/drawio — repo: github.com/jgraph/drawio — the veteran manual canvas. excalidraw/excalidraw — repo: github.com/excalidraw/excalidraw — the hand-drawn collaborative whiteboard. cathrynlavery/diagram-design — repo: github.com/cathrynlavery/diagram-design — a new species: an agent skill that outputs editorial-grade diagrams.
Four Projects, Four Numbers
The hard numbers first. Stars and licenses below were measured via the GitHub API on 2026-10-13:
| Project | Stars | License | Language | One-line profile |
|---|---|---|---|---|
| mermaid-js/mermaid | 90,636 | MIT | TypeScript | Diagrams as code, rendered natively in Markdown |
| jgraph/drawio | 8,722 | Apache-2.0 | JavaScript | Veteran manual canvas, huge shape library |
| excalidraw/excalidraw | 133,741 | MIT | TypeScript | Hand-drawn whiteboard, fast collaboration |
| cathrynlavery/diagram-design | 52,787 | MIT | HTML | Agent skill for editorial-grade diagrams |
One caveat before anyone reads that table as a leaderboard. draw.io shows just over 8,700 stars, yet you see diagrams drawn in draw.io almost every day — architecture maps, deployment topologies, ops runbooks. Its real user base is far larger than the star count of this one source repository; stars measure the repo, not the product, and ranking all four by stars would be deeply unfair to draw.io. Likewise, Excalidraw's 133,741 stars say more about how broadly the hand-drawn whiteboard aesthetic resonates than about which tool is "best."
The licenses, at least, are uniform: MIT for Mermaid, Excalidraw, and diagram-design, Apache-2.0 for draw.io — no licensing surprises for team adoption.
Mermaid: Diagrams Travel with Code, at a Visual Cost
Mermaid's core proposition is to write diagrams as text. A Markdown-like DSL describes flowcharts, sequence diagrams, and gantt charts; the engine renders. Its real moat is not rendering quality but distribution: GitHub renders Mermaid code blocks natively in Markdown. Paste a fenced block into a README or a pull request description and every collaborator sees the diagram with zero configuration.
That is what "diagrams travel with code" means in practice. You change a diagram in a branch, review it in a pull request, and git diff pinpoints exactly why a connector moved last month. The diagram's lifecycle stays synchronized with the codebase — something none of the other three routes offer.
The cost is equally clear. Mermaid's theming is the renderer's theming: the things a designer wants to tune — precise spacing, brand palettes, hairline strokes — are essentially out of reach. Complex layouts are a chronic weakness too: once node counts grow, connectors start crossing the canvas, and the reader suffers more than the author.
So Mermaid's best seat is unambiguous: diagrams that live next to code, change every sprint, and value iteration speed over pixel control. One engineering tip: the same DSL can render slightly differently across engine versions. If a diagram must live in docs for years, pin the version in CI and commit rendered assets alongside the source — the standard closing move for diagram-as-code.
draw.io and Excalidraw: Two Temperaments of the Manual Canvas
draw.io is where many diagramming careers start. It opens in a browser and just works, with enormous shape libraries covering architecture, networking, UML, and the cloud icon sets of AWS and Azure. The .drawio file format is editable XML, so diagram sources can live in repositories and travel with documents; you can even embed a diagram inside a PNG and reopen it for editing later. It wins on maturity, completeness, and price.
Excalidraw goes to the opposite pole: hand-drawn. Every shape is a wobbly, sketchy stroke that looks like it was dashed onto a whiteboard. This is not a defect — it is a deliberately engineered conversation posture. Project a perfectly symmetric diagram in a review meeting and people instinctively feel the design is already decided; project a hand-drawn sketch and people cannot help saying "what if we changed this?" The aesthetic lowers the social cost of dissent; paired with real-time collaboration and shareable links, it is a weapon for design reviews and remote brainstorms.
Set side by side, the difference is temperament: draw.io is mature because it is all-purpose, Excalidraw is agile because it is atmospheric. The first produces formal deliverables; the second keeps unfinished conversations moving.
One selection nuance: .drawio files are XML, but their diff readability is mediocre — fine for "the whole file lives in the repo," less fine for line-by-line change review. The same goes for .excalidraw files. Manual-canvas sources version fine; expecting Mermaid-grade diffs from them is asking too much.
diagram-design: Not a Website, a Design System for Agents
The fourth route is the strangest. diagram-design is not a website and not a canvas — it is an agent skill, installed with npx skills add cathrynlavery/diagram-design, that injects a full editorial-grade diagram design system into coding agents such as Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, and Pi. An agent that normally produces sketch-level output suddenly draws diagrams fit for a launch stage.
The design system is unusually strict. Everything aligns to a 4px grid. Strokes are 1px hairlines. No shadows. Corner radius capped at 10px. A single accent color across the entire diagram. Target information density of 4 out of 10 — deliberate whitespace instead of a spiderweb of arrows. There are 44 diagram types (per the README) covering high-frequency development views: architecture, sequence, roadmaps, comparison matrices. Three variants — minimal light, minimal dark, full editorial — map to three environments: marketing site, dark IDE demo, magazine-style long read.
Output is self-contained HTML with inline SVG: embeddable directly into web pages or documents, exportable to SVG and PNG, and checkable in CI for text overlap and boundary clipping — "did the label collide with a box" no longer depends on a human squinting.
A line of market background, clearly secondhand: third-party roundups (theaileaderboard) rank Napkin AI first among 2026 AI diagram tools, and paid products like Eraser (Starter $15/user/month) and Mermaid Chart (Plus $10/user/month) have fans. Those are hosted services, a different dimension from these four self-hosted routes, so they get one sentence.
The Verdict: Choose by the Diagram's Downstream Purpose
Which route to pick depends not on raw strength but on who sees the diagram and in what form it lives. The conclusions below follow the comparison table in the diagram-design README (secondhand framing — sensible, and it matches the technical bones of each route):
- The diagram lives beside code, changes every sprint, and needs clean git diffs — use Mermaid. The source is text, the diff is readable, rendering follows the repository.
- Hands-on whiteboarding, collaborative sketching, discussions still in flux — use draw.io or Excalidraw. Formal deliverables lean draw.io; speed and atmosphere lean Excalidraw.
- Publication-grade, presentation-grade, brand-consistent output — use diagram-design. Standards up front, the agent executes, the result can go straight on a big screen.
Choosing by downstream purpose reduces to three questions: who is the final audience? How often will it change? Who may change it? Answer those and the route picks itself.
Matching Scenarios to Routes
The architecture diagram lives in the repo and moves every sprint. Use Mermaid, no contest. The source goes into git, gets reviewed in pull requests, and gets tracked in diffs. When a diagram's lifecycle is coupled to the codebase, text is the only sensible form.
Design reviews, remote brainstorms, drafts that keep changing. Pick draw.io or Excalidraw. At this stage the diagram's job is to make the discussion happen, not to look good. Once the design settles, the draft has finished its mission.
Publishing, presenting, brand consistency. diagram-design takes the stage. Its three variants and its 4/10 density target are built precisely for "going on the big screen."
The best value, though, is the combination. My recommended workflow has three stages: draft in Excalidraw until the discussion settles; write the settled elements into a prompt and hand it to an agent equipped with diagram-design for the editorial redraw; archive the published version together with the redraw prompt. The sketch buys discussion speed, the redraw buys polish, and the archive buys the ability to explain, three months later, why it was drawn this way.
One reminder: these conclusions are weights, not commandments. None of the four is a universal answer — only different answers to where your particular diagram is going.
Honest Boundaries
Tool comparisons fail when they only report the good parts. The pitfalls, without varnish:
- Mermaid: complex layouts tangle easily and visuals are uncontrollable. Rendering can shift across engine versions — pin the version and render in CI.
- draw.io: free but interaction-heavy, with limited automation; bulk diagram generation requires detours.
- Excalidraw: the hand-drawn style cuts both ways; formal deliverables can read as casual.
- diagram-design: output quality depends on the model you pair it with. The same prompt can produce different layouts on two runs, with no pixel-level reproducibility. There is no native .drawio canvas and no diff-able diagram text (per the README).
diagram-design's limits deserve expansion. Its output rides on model capability — swap in a weaker model and the same spec is enforced noticeably worse. Layout nondeterminism is a hard blocker for scenarios demanding "today's diagram must be identical to yesterday's." The absence of a .drawio canvas means it cannot manage the diagram's whole lifecycle; it manages "draw one good diagram." Lacking diff-able text, it cannot enter Mermaid's home turf — not a bug, a property of the route.
One more implicit trap: stars do not equal fit. Excalidraw's 133,741 stars will not draw your launch slide, and diagram-design's 52,787 stars are worth nothing inside a git diff. Star counts are a crude proxy for community heat, not a selection criterion.
FAQ
Q1: What are good Mermaid alternatives?
A1: Four mainstream routes: in diagram-as-code, Mermaid has siblings such as D2 and PlantUML; for manual canvases, draw.io is the standard bearer; for hand-drawn collaborative whiteboards, Excalidraw leads; for agent-generated editorial-grade diagrams, install diagram-design (github.com/cathrynlavery/diagram-design). Which to choose depends on the diagram's downstream purpose: into git diffs, Mermaid; collaborative whiteboarding, Excalidraw; published presentations, diagram-design.
Q2: Should I use draw.io or Excalidraw?
A2: It depends on the stage and formality of the diagram. If the design is still under discussion and multiple people need to scribble in real time, Excalidraw's hand-drawn style and collaboration experience fit better. If you need a structurally rigorous diagram that can ship as a formal deliverable, draw.io's shape libraries and .drawio file format are more dependable. Both open in a browser instantly; try each for ten minutes before deciding.
Q3: How do I render Mermaid diagrams on GitHub?
A3: Just write them. Wrap the DSL text in a fenced code block tagged with mermaid inside any Markdown file or pull request description, and GitHub renders it natively with zero configuration. Diagrams travel with code — Mermaid's core advantage — and git diff tracks every change along the way.
Q4: Who is diagram-design for?
A4: Developers who already work with coding agents such as Claude Code, Cursor, or Copilot and need publication-grade or presentation-grade diagrams. It installs as an agent skill (npx skills add cathrynlavery/diagram-design), but output quality depends on the model you pair it with, and the same prompt can yield different layouts on two runs — be careful in scenarios that demand pixel-level reproducibility.
Q5: Are all four projects open source, and is commercial use safe?
A5: Stars and licenses were measured via the GitHub API on 2026-10-13: Mermaid (90,636 stars, MIT), draw.io (8,722 stars, Apache-2.0), Excalidraw (133,741 stars, MIT), diagram-design (52,787 stars, MIT) — no licensing obstacles for commercial use. Note that draw.io's user base is far larger than its source repository's star count; stars refer to the repository only.
Closing: The Diagram's Destination Decides the Tool
Behind every search for "Mermaid alternatives" is a team stuck on a concrete scenario: an architecture diagram in the README that renders wrong after every upgrade, a whiteboard photo from a review meeting that nobody opens again, a midnight scramble before a big presentation, patching screenshots. Switching away from Mermaid is not the cure, because the problem usually is not the tool — it is that nobody ever took the diagram's destination seriously.
Return to the question the September 15 comparison kept circling: who owns the diagram after it is generated, and in what form does it persist? Its real subtext: who consumes it downstream — a git diff, a collaborative whiteboard, or a stage under lights?
Answer that clearly, and the four routes fall into place on their own. Selection is never a vote for a tool; it is a portrait of a use.