Why Mermaid is the wrong tool for code review

Mermaid is a good tool aimed at a different problem. Its own documentation states the goal plainly: the main purpose of Mermaid is to help documentation catch up with development. Code review wants the opposite property. A diagram of a pull request is disposable, has to be redrawn every time somebody pushes, and stops being worth anything the moment the branch merges. Since LinearB's 2026 benchmarks put AI-assisted pull requests at 408 lines at the 75th percentile against 157 unassisted, the redrawing is the whole job. Five properties of Mermaid work against that, and one of them is not the one people usually name.

What Mermaid is genuinely good at

I use Mermaid. I want to be specific about where, because most criticism of it is unfair and I would rather not add to that pile.

It renders natively on GitHub, announced on 14 February 2022. GitHub's docs now list diagram rendering in issues, discussions, pull requests, wikis and Markdown files, so a fenced mermaid block becomes a picture with no image hosting, no build step and no plugin. That is a remarkable amount of reach for a text format.

The source is text, so it diffs, reviews and merges like code. An architecture decision record with a state machine in it stays correct because changing the state machine is a pull request like any other. This is the doc-rot argument and it holds.

It covers a lot of ground: flowcharts, sequence diagrams, class diagrams, state diagrams, entity relationship diagrams, Gantt charts and more than twenty others. A team that learns one syntax gets all of them.

It is MIT licensed, created by Knut Sveidqvist and first released in 2014, and it is still moving: since version 11.5.0 in March 2025, a flowchart edge given an id takes e1@{ animate: true }, with fast and slow speeds. People who say Mermaid cannot animate are working from an old memory.

For a system diagram in a README that a person updates on purpose, Mermaid is the right answer and I would not reach for anything else.

The first problem is that you have to write it

Every other objection is downstream of this one. Mermaid is a notation, and a notation produces nothing on its own. Somebody has to sit down, read the change, decide what the picture is, and type it.

On a branch a human wrote over three days, that is a reasonable ask once. On a branch an agent pushed to six times before lunch, it is not going to happen, and what you get instead is a diagram that described commit three of eleven and now quietly lies. A reviewer who catches the mismatch stops trusting the diagram. A reviewer who does not is worse off than if the pull request had carried no picture at all.

Mermaid was built to stop documentation rotting, and a pull request diagram is meant to rot.

You can automate the writing, and tools do. CodeRabbit, as of September 2026, generates Mermaid sequence diagrams as part of its pull request summaries, which solves the authorship problem and inherits everything below. Prices and features in that category move every quarter, so check before you rely on it.

Layout is the engine's decision

Mermaid lays flowcharts out with dagre by default, with ELK available since version 9.4 as an alternative renderer for larger and more complex diagrams. Both are automatic layout algorithms, which means the position of any node is a function of the whole graph. Add one node and things move. The documentation describes how to choose a renderer and promises nothing at all about whether the same source lays out the same way twice.

In documentation that cost is invisible, because the diagram changes only when a person decides it should. In review it is real. A reviewer opens the same pull request on Tuesday after four more commits, and the boxes are not where they were on Monday. The picture they had half-learned has to be learned again, and the second learning is not cheaper than the first.

Automatic layout is not the enemy here. PR Lens computes layout too. The difference is what the layout is allowed to do: every lane is a fixed width, a constant rather than anything derived from what the lanes hold, and depth is counted within a lane. So adding a node to one lane leaves every card in every other lane exactly where it was. That costs something, since a lane holding one short label is wider than it needs to be. Stability is worth more.

There is no word for what the change did

This is the gap that matters most and the one Mermaid cannot close without becoming a different tool.

A pull request diagram has to say, per component, one of four things: this is new, this was modified, this was deleted, this was already here. Mermaid has no concept of any of that. You express it with classDef, colours you choose, and a legend, and now the meaning of green in your diagram is a local convention that a reviewer has to read before the picture is worth anything. Read the legend, map the colours, then read the diagram. The reading you were trying to avoid has just moved.

There is a second half to it. The four states include unchanged, and a hand-written Mermaid diagram of a change almost never includes unchanged components, because writing them out is work with no obvious payoff for the author. That payoff is the entire question the reviewer has, which is what blast radius diagrams is about. A diagram containing only the parts that changed is a diff with rounded corners.

Every box carries the same weight

Mermaid's default output gives you boxes and lines. Same shape, same stroke, same emphasis, unless you style each node yourself. So the one connection the change is really about looks exactly like the seven that were already there.

The landing page for PR Lens says "Not Mermaid" and that line is about this. Depth, weight, glyph and colour carry meaning in the renderer: a node's kind decides its icon, an edge can be marked as the hero connection and gets a glow, retired components are ghosted and struck through, and motion marks the connections that carry traffic rather than merely existing. None of that is decoration. Each mark is one distinction a reader gets without reading a word.

You can do a fair amount of that in Mermaid with enough classDef and linkStyle. What you cannot do is get it consistently across every diagram every reviewer sees, because the styling lives in whoever wrote that particular block.

It renders where JavaScript runs

The last one is small but it bit us. GitHub's announcement post describes the mechanism: when it meets a code block marked mermaid, it generates an iframe that passes the raw syntax to Mermaid.js, which turns it into a diagram in your local browser. The same post is explicit that a client requesting the content in a non-JavaScript environment, such as an API request, sees the original Markdown code instead. GitHub's docs add that a third-party Mermaid plugin can produce errors on GitHub's own syntax, and they never state which Mermaid version GitHub runs. The documented way to find out is to put an info line inside a mermaid block in a comment and read the answer off the page.

For a human reading a pull request in a browser that is all fine. For anything programmatic reading the same thread, and for deciding whether a feature released in Mermaid last month will work in a comment today, it is guesswork. An image has none of that ambiguity, which is why PR Lens ships SVG with declarative animation and no script in it. The mechanics of that trade are in animated SVG in GitHub comments.

When you should still write Mermaid in a pull request

Two cases, and they are good ones.

When the diagram is an argument rather than a description. "Here are the three ways we could do this and why I picked the second" is a case you are making, and you should write it by hand in whatever notation makes the case clearest.

And when the diagram is going to be committed. A state machine that belongs in the docs should be added in the same pull request as the code it describes, in Mermaid, in a file, where it will be reviewed and maintained.

What neither case needs is for a person to hand-draw the shape of the change on every push. That job wants a machine, a fixed grammar, and a picture that redraws itself. If you are weighing the DIY route specifically, PR Lens vs writing a Mermaid diagram in the PR description yourself is the direct comparison, architecture, sequence or data-flow diagram covers which picture you want, and how to visualise a pull request as a diagram ranks all five ways.