Documentation diagrams rot because they live in the wrong place - a binary file in some drawing app that nobody opens, drifting further from the code with every change. Mermaid fixes the root cause by making diagrams text. You describe a flowchart, sequence diagram, ER diagram, or state machine in a small declarative syntax, and Mermaid renders it - and because it's just text, it lives in your repo, diffs in a pull request, and updates alongside the code it documents.
Diagrams as Code
The syntax is compact and readable on its own, even before it's rendered:
flowchart LR
A[React island] -->|fetch| B(JSON:API)
B --> C[(Drupal DB)]
That's a complete, versionable diagram. Change a node, commit it, and the picture changes with the code.
Rendered Where You Already Work
GitHub and GitLab render Mermaid inside Markdown automatically, and it's supported across many editors, wikis, and static-site generators. You rarely need to run anything yourself - the diagram shows up wherever your docs are read.
Many Diagram Types
Beyond flowcharts, Mermaid covers sequence diagrams, entity-relationship diagrams, state diagrams, class diagrams, Gantt charts, and more - enough to document most of what a software project needs to explain.
Rough Edges and Limitations
- Auto-layout, limited control. Mermaid places nodes for you; for pixel-perfect layouts a manual drawing tool still wins.
- Big diagrams get busy. Very large graphs can render cluttered - often a sign to split them.
- Syntax quirks per type. Each diagram type has its own rules and the occasional sharp edge.
- Renderers vary. A newer feature may render in one place and not yet in another.
For architecture notes, data models, and flows that should stay in sync with the code, Mermaid is the pragmatic default: diagrams that live in the repo and never fall out of date because updating them is just editing text.
Internal link suggestion: link "data model" to a future post on documentation tooling, or to the Repomix post when explaining a codebase to an AI.
