What is Mermaid? A Beginner's Guide to Diagrams as Code
If you have ever pasted an architecture diagram into a README only to watch it drift out of date, Mermaid is the fix. Mermaid is an open-source JavaScript-based diagramming tool that renders diagrams from plain text. You describe the diagram in a simple syntax, and a layout engine draws it — no dragging boxes, no aligning arrows, no exported PNG files to keep track of. This guide explains what that means in practice, what the syntax looks like, and how to make your first diagram in the next few minutes.
Diagrams as code, explained
The phrase “diagrams as code” means the source of a diagram is text you can store, diff, and review like any other file. A diagram written in Mermaid lives in a .md file or a .mmd file, sits next to your source code in the repository, and changes through the same pull request workflow as everything else. When someone adds a retry branch to a flow, the diff shows one new line — not a binary blob that reviewers have to open in a separate application.
This model inverts the usual maintenance problem. With drawing tools, the diagram is an artifact that someone must remember to re-export after every change, and stale diagrams are the norm. With Mermaid, updating the diagram is editing text, so it happens in the same commit as the change it describes. The diagram stops being a snapshot and becomes part of the codebase.
What Mermaid syntax looks like
Here is a complete, working Mermaid diagram — a deployment pipeline:
flowchart TD
A[Push to main] --> B{Tests pass?}
B -- Yes --> C[Build image]
B -- No --> D[Alert the team]
C --> E[Deploy to staging]
E --> F{Smoke tests pass?}
F -- Yes --> G[Deploy to production]
F -- No --> DReading it line by line: the first line, flowchart TD, declares the diagram type and sets the direction to top-down. A[Push to main] defines a node — the letter is an internal id, and the text in square brackets is the label. Curly braces like B{Tests pass?} render a diamond, which is how you draw decisions. Arrows are written with -->, and you can attach labels to them with the double-dash form: B -- Yes --> C. That is most of the language. If you can write a bulleted list, you can write a Mermaid diagram.
Two small rules prevent most beginner errors. First, if a label contains parentheses, brackets, or colons, wrap the whole label in quotes: A["Deploy (prod)"]. Second, node ids must be unique — reusing an id silently merges two nodes into one, which is confusing to debug.
The diagram types you will actually use
Mermaid supports more than a dozen diagram types, but a handful do most of the work in real projects. Flowcharts map processes, decision trees, and on-call runbooks — the user onboarding flowchart is a typical example. Sequence diagrams show how messages move between actors and services over time, which makes them the default choice for API documentation; the sequence diagram guide covers the syntax. Class diagrams and entity-relationship diagrams document code structure and database schemas. State diagrams model the lifecycle of an order or a session. Gantt charts, pie charts, mindmaps, and timelines round out the set for planning and reporting pages.
The practical test is simple: if a diagram describes something with steps, states, or relationships, Mermaid can draw it. If it is a freeform illustration — a marketing graphic, a floor plan — it cannot, and that is by design.
Why teams replace image files with Mermaid
The benefits compound once a team standardizes on text diagrams. Version control works properly: every change is a reviewable diff, and history is a git log away. Review quality improves because a reviewer reads what changed instead of squinting at two exported images. Onboarding improves because new engineers can read the diagram source and the code in the same place. And diagrams render inline on GitHub and GitLab, so a README with a Mermaid block is self-contained — no image attachments, no broken links to a drive somewhere.
There is also a consistency benefit. Because the layout engine positions everything, every diagram in your docs shares the same visual language. Nobody’s hand-drawn arrows or idiosyncratic color schemes creep in, and nobody spends an afternoon nudging boxes.
Where Mermaid is not the right fit
Honesty about the trade-off: Mermaid gives up manual layout control. You cannot place a node at specific coordinates, and complex diagrams occasionally arrange themselves in ways you would not have chosen. If you are producing a polished one-off visual for a slide deck or a poster, a canvas tool gives you finer control. If your diagrams need vendor-specific stencils — network racks, floor plans — a specialized tool is the better fit. Mermaid is optimized for diagrams that live with documentation and change often, and it is deliberately not optimized for pixel-perfect artwork.
Make your first diagram in five minutes
Open the free Mermaid editor, paste the pipeline example above, and change the labels to match a real process from your work. Add a node, draw an edge to it, and watch the diagram update as you type — rendering happens locally in your browser. When it looks right, copy the text into your README or docs page; GitHub and GitLab will render it automatically.
To go further, pick a template close to your use case and edit it: the API authentication sequence diagram for service interactions, or the onboarding flowchart above for product flows. The fastest way to learn the syntax is to modify working diagrams one line at a time — and with text as the source, every one of those lines is versioned, reviewable, and yours to change.