Mermaid vs draw.io: Choosing Auto-Layout or Manual Diagram Placement

For a docs-as-code repo where humans review diffs and coding agents now edit the pictures too, the practical answer is: default to Mermaid for most architecture diagrams, reserve draw.io for the few cases where exact placement is a hard requirement, and treat Reladraw’s relative-placement syntax as a promising pilot rather than a standard. The consequence is a shift in who owns layout: from someone dragging nodes, to whoever writes and reviews placement rules in text.

The decision is who owns placement

Diagram tools look similar in a gallery and behave very differently in a repository. The useful question is not “which renders prettiest,” but “who decides where a node goes when the diagram changes.” If a layout solver decides, the author gives up exact placement and gains small, reviewable text diffs. If the file stores absolute coordinates, the author keeps placement control and pays for every move, every rename, and every regenerated diagram. Groundy’s earlier agent diagram comparison framed the broad tool choice; this piece narrows it to placement control, because that is the axis that changes review and agent editing.

The demand side is already real. In one Hacker News workflow discussion, a practitioner describes having an agent enrich a plan with architecture diagrams and data models, editing those artifacts, and letting the implementation agent read them later so the architecture does not need to be re-explained. Once diagrams sit beside plans and code in that loop, the diagram source becomes part of the change surface. A format that is easy for a human to drag around may be awkward for an agent to patch safely, and a format an agent can emit quickly may be frustrating when a reviewer has a specific picture in mind.

Three placement models, one review question

The evidence supports a spectrum with two well-evidenced poles and one newer middle position. Mermaid anchors the auto-layout end: a third-party editor describes the model as “write simple text, get professional diagrams,” with no coordinate picking and PNG, SVG, and PDF export, though that feature list is a vendor page rather than official Mermaid documentation. At the other end, Reladraw’s README characterizes draw.io and Excalidraw as absolute-placement tools where humans click and drag nodes and agents recalculate coordinates inside verbose XML. Between them, Reladraw proposes relative placement: say what sits below or right of what, and let the tool resolve geometry.

That table should be read as a decision lens, not a benchmark. The strongest comparative language about draw.io comes from Reladraw’s own README, an interested party. Still, the mechanism is clear enough to reason from: the more geometry is stored literally in the file, the more an edit becomes coordinate maintenance; the more geometry is derived from declarations, the more review becomes a check of intent rather than position arithmetic.

Mermaid gives up control in a useful place

Mermaid’s strength for repos is that the authoring unit is close to the review unit. A flowchart, sequence diagram, or ER diagram can be expressed as text, rendered to SVG, and diffed like the surrounding documentation. The Mermaid Editor page advertises 21-plus diagram types and watermark-free SVG export on the free tier; treat those as vendor claims, but the core model is consistent with the auto-layout end of the spectrum: text in, diagram out, no manual coordinate picking.

The tradeoff is that auto-layout has opinions. When a team only needs “these services call this database,” a solver is often good enough and saves time. When the architecture has a visual argument, such as “the public edge is above the internal services, the data plane is to the right, and the legacy system hangs off the side,” solver output can feel wrong even when every edge is correct. That is an inference from the placement model, not a documented Mermaid failure.

For agent editing, though, the absence of coordinates matters. An agent asked to add a queue between an API and a worker can insert two lines and an edge without recomputing the canvas. A human reviewer sees the added relation rather than a block of changed x and y values, which is exactly the property that makes text diagram formats attractive in the same repos where agents already patch markdown plans.

draw.io keeps control and makes edits expensive

Reladraw’s README states the manual-placement critique bluntly: draw.io and Excalidraw “allow absolute placement,” but that means more effort for “humans clicking and dragging nodes around or agents recalculating coordinates and editing verbose XML source code files,” according to the Reladraw README. It is a competitor’s framing, not draw.io’s own documentation and not an independent study of draw.io in git.

Even with that caveat, the underlying cost is easy to understand. Absolute placement stores the answer to “where is everything?” inside the artifact. Move one node and the file may need many coordinate updates. Rename a node and the geometry remains, but an agent regenerating the diagram from a prompt may produce a different arrangement unless it also manages positions. For a human in a visual editor, that cost is the point: exact control. For an agent asked to make a minimal architectural change, the same representation can turn a semantic edit into a geometry problem.

There is a boundary here that matters for procurement-style decisions. Nothing in Reladraw’s README or the practitioner threads documents actual draw.io merge conflicts, so it would be wrong to claim that draw.io always produces unreviewable diffs. Teams can mitigate with exported SVGs, disciplined one-diagram-per-file rules, or “edit only in the GUI” conventions. The narrower supported claim is that absolute placement concentrates control in coordinates, and coordinates are expensive for text-first editing. That is enough to make draw.io a specialist tool in an agent-edited docs repo, not a default.

Reladraw’s middle ground is explicit relations

Reladraw’s pitch is that authors can keep text editability while saying more about placement than pure auto-layout allows. Its example syntax is direct:

node app "Web app"
node app.ui "Interface"
node app.api "API" below app.ui

node store "Database" right of app level with app

The same Reladraw README says positions are relative, so authors do not manually pick coordinates, and describes a parser, layout engine, and SVG renderer written in TypeScript with zero runtime dependencies. Mechanically, this splits placement into two layers: humans and agents state relations that carry intent, while the tool resolves those relations into a renderable SVG. The hoped-for benefit is that an agent can change “API below Interface” or “Database right of app” without doing canvas arithmetic.

The maturity signals are the caution. Reladraw self-reports “Version 0.8.0. Early stage, but works,” and warns, “The language isn’t stable yet, so expect the syntax to change.” Those are the project’s own words, cited to the Reladraw README, not an outside audit. The agent benefit is likewise design intent in the README, not a measured result: the project reports no agent-edit success rates, no review-time comparison against Mermaid, and no maintainer count.

The agent-skill install is npx skills add reladraw/reladraw -g -a claude-code, verbatim from the Reladraw README. The -g flag installs the skill for every agent you use; leaving it off scopes the install to the current project, and -a narrows the target to a single agent such as Claude Code. The README also notes that the command copies the skill as it exists when you run it, so picking up a newer release means re-running it. A snapshot install is not automatically bad; it can make behavior reproducible. But paired with unstable syntax, it means a pilot can pin the skill and still break the diagram language on the next upgrade.

Agents are already crossing the diagram boundary

The reason this choice is urgent is not a release note; it is workflow change. The agent context workflow on Hacker News has diagrams living alongside the plan and code, then read directly at implementation time. That collapses the old separation between “documentation picture” and “machine-readable context.” If an agent consumes the diagram later, edits to the diagram are edits to the agent’s future instructions. Review quality matters more, not less.

There is also a competing representation that avoids text syntax entirely. The Show HN thread for Davia describes an open-source local workspace where text lives in a Notion-like editor, diagrams live on editable whiteboards, and everything can be modified in the IDE or the workspace. That is a live counterpoint to the whole “diagram as code” premise: if the agent can write an editable whiteboard that stays locally inspectable, maybe the answer is not a better textual placement language but a better shared canvas. The Show HN post does not compare Davia’s durability, diff behavior, or repo fit against Mermaid, draw.io, or Reladraw, so it belongs in the decision as a challenge to assumptions, not as a recommended replacement.

What the evidence cannot settle

This framework should not be overextended. The comparative claims are anchored by Reladraw’s README on one side and a third-party Mermaid marketing page on the other, with practitioner threads supplying demand but not measurements. None of those sources covers D2 or Graphviz layout behavior, draw.io’s own documentation, Mermaid behavior on large graphs, or agent-editing success for any representation. That silence is not proof of absence; independent comparisons may exist elsewhere.

That changes how to run a pilot. Do not standardize on Reladraw because the syntax is elegant. Pilot it on one repo where diagrams are already agent-edited, and predefine failure: syntax churn after upgrade, rendered output drifting from reviewed intent, skill snapshots going stale, or reviewers unable to tell whether a relation edit changed meaning or merely layout. Keep Mermaid diagrams rendering in CI if SVG output is part of review. Keep draw.io where a human-owned visual artifact must remain exact, such as a regulated network zone diagram, but do not assume from this evidence that it will merge badly; verify that in your own repo history.

Choose the burden you want in code review

The practical verdict is bounded but usable. Keep Mermaid as the production default for docs-as-code architecture diagrams because text-in, diagram-out authoring matches diff review and avoids coordinate maintenance; the export and diagram-type claims came from a vendor page, so confirm specific rendering needs locally. Reserve draw.io or Excalidraw for diagrams where exact placement is non-negotiable and a human owns the canvas. Trial Reladraw only as an experimental middle ground: relative placement is the most interesting answer to agent editing, but v0.8.0, unstable syntax, snapshot skill installs, and unmeasured agent benefits keep it out of the critical path.

The limitation to remember is that the evidence shows a real decision axis, not a winner. It shows practitioners want agents to carry diagrams forward as context, shows Mermaid’s text model, shows Reladraw’s own account of draw.io’s coordinate cost, and shows an editable-whiteboard alternative in Davia. So the safe standard is procedural: put diagram sources under the same review discipline as code, prefer representations where a diff expresses intent, and make any tool that promises agent-friendly layout prove it inside one repository before it becomes the house style.

Frequently Asked Questions

How do I install the Reladraw agent skill?

The agent-skill install is npx skills add reladraw/reladraw -g -a claude-code, verbatim from the Reladraw README. The -g flag installs the skill for every agent you use; leaving it off scopes the install to the current project, and -a narrows the target to a single agent such as Claude Code.

What are the main risks of using Reladraw in a production environment?

Reladraw self-reports “Version 0.8.0. Early stage, but works,” and warns, “The language isn’t stable yet, so expect the syntax to change.” Those are the project’s own words, cited to the Reladraw README, not an outside audit. The agent benefit is likewise design intent in the README, not a measured result: the project reports no agent-edit success rates, no review-time comparison against Mermaid, and no maintainer count.

When should I use draw.io instead of Mermaid?

Reserve draw.io or Excalidraw for diagrams where exact placement is non-negotiable and a human owns the canvas.