Diagrams as code with Mermaid: what it does well and where it stops

What it is

Mermaid (cited) is a JavaScript-based tool that renders Markdown-inspired text definitions into diagrams: flowcharts, sequence diagrams, class and state diagrams, entity-relationship diagrams, Gantt charts and more. Its documentation states its purpose as helping documentation catch up with development, calling doc-rot a catch-22 it helps to solve. GitHub (cited) renders a fenced code block with the mermaid language identifier as a diagram in Markdown files, issues and pull requests; other wikis and static-site generators embed the same library.

Why it matters

A diagram stored as an image is edited in a tool nobody on the team still has, and the review shows a binary change. A diagram stored as text sits next to the code it describes, is changed in the same pull request, and its diff shows which arrow moved. That is the property that keeps architecture sketches, state machines and request flows current.

How to apply

• Keep one diagram per question ("what calls what during checkout"), with a dozen nodes at most; split rather than grow.
• Use the diagram type that matches the statement: sequence diagrams for ordered interactions, state diagrams for lifecycles, flowcharts for decisions, ER diagrams for data.
• Quote labels that contain punctuation and avoid reserved words as node identifiers; parse errors are the most common failure.
• Add accTitle and accDescr (cited) so the rendered SVG carries an accessible title and description for screen readers and for agents that read the page as text.
• Put the diagram in the document it explains, not in a separate diagram folder, and mention in the text what the reader should see.
• Pin the Mermaid version in your own site build; check that the platforms you publish to render the diagram types you use.

Pitfalls

Layout is automatic; you can hint direction and grouping but not place nodes precisely, and a diagram that needs exact placement belongs in another tool. Large diagrams become unreadable and slow. Rendering depends on the Mermaid version the viewer embeds, so a diagram can render on one platform and fail on another. Viewers that do not run the library (plain Git hosting, e-mail, some PDF pipelines) show the source text; keep the text readable on its own. A diagram is still a claim about the system and rots like prose unless it is reviewed with the code it describes.