What Mermaid is
Mermaid is a text-based diagramming language. A few lines of indented syntax describe a flowchart, sequence diagram, entity relationship, Gantt chart, or state machine, and a renderer turns them into a picture. GitHub, GitLab, Obsidian, most documentation systems, and this site render it natively inside Markdown.
The consequence that matters is that the diagram becomes text, and text is a first-class citizen everywhere. It lives in your repository next to the code it describes. It diffs line by line, so a pull request shows that a step was added rather than showing two images. It gets reviewed and commented on like anything else. And crucially, it cannot silently go stale in the way a PNG exported eighteen months ago does — because updating it is editing three lines rather than finding the source file, opening a design tool, and re-exporting.
Why researchers use it
- The diagram is versioned properly — a text source in Git, with a real history and a readable diff.
- It renders where people already look — a flowchart in a GitHub README appears without anyone downloading anything.
- Restructuring is editing, not dragging — insert a step in a ten-node pipeline by adding one line, and the layout re-flows.
- It stays current — because updating costs seconds, the diagram in your documentation actually matches the pipeline, which is more than most diagrams manage.
- Language models write it well — describing a workflow in prose and getting Mermaid back is a genuinely reliable use of an AI assistant, since the output is checkable at a glance.
Where it fits in a research workflow
Mermaid belongs to documentation: the pipeline diagram in your repository README, the methods flowchart in a Quarto document, the study-design sketch in an Obsidian note. It is the diagramming tool for things that change.
The natural pairing is with the repository — a Snakemake or Nextflow pipeline documented by a Mermaid flowchart in the same repo, both updated in the same commit. Where it hands off: diagrams.net when you need control over exactly where things sit, Excalidraw when you are sketching rather than documenting, and Inkscape when the diagram becomes a publication figure — though the Mermaid-to-Inkscape route means that handoff can start from your existing source rather than from scratch.
Getting started
Fifteen minutes.
- Open the live editor at mermaid.live and type a three-node flowchart. The syntax is simple enough that reading one example teaches most of it.
- Paste the same block into a GitHub README inside a fenced code block labelled
mermaid. Seeing it render with no plugin, no upload, and no image file is the moment the value becomes obvious. - Add one to a repository you maintain — the pipeline overview you have been meaning to write down.
- The step people skip: theme it once per project. Mermaid’s defaults are generic, and a small theme configuration makes diagrams match your documentation or your house identity rather than looking like every other Mermaid diagram on the internet.
Mermaid vs the alternatives
| Alternative | Does it better | Pick it if |
|---|---|---|
| diagrams.net | Exact placement and control over complex layouts | The layout matters and auto-routing fights you |
| Excalidraw | Speed and freedom for sketching | You are thinking, not documenting |
| Inkscape | Publication-grade precision and typography | The diagram is a journal figure |
| TikZ | Total control inside a LaTeX document | The figure must match the manuscript exactly |
Mermaid wins whenever the diagram must stay in sync with something that changes. It loses whenever exact layout is the requirement.
Cost, licensing, and your data
Free and open source under the MIT licence, with a large user base and active development. There is a commercial hosted product from the same team for teams that want a managed editor, but the language, the renderer, and every integration are free.
Nothing leaves your machine: rendering happens locally in whatever tool displays the Markdown, and the source is text in your own repository. That makes it appropriate for documenting a pipeline that processes sensitive data, where a cloud diagramming service would be a question to answer. The one dependency to note is renderer version — Mermaid’s syntax has expanded over time, so a diagram using recent features may not render in an older environment, which occasionally surfaces when a journal’s Markdown pipeline is behind.
The honest review
Strengths. Mermaid solves the staleness problem, which is the real failure of diagrams in research documentation. Every project has a beautiful architecture diagram made once and wrong within six months; a Mermaid diagram gets fixed because fixing it costs nothing. Combined with native rendering in the places research code already lives, it makes documenting a pipeline something people actually do.
Limitations. Layout is automatic and only partially steerable, and this is the real constraint. Simple diagrams look fine; past roughly a dozen nodes with cross-links, the auto-layout produces crossings and asymmetries you cannot fix, and the time spent coaxing it is time you should have spent in a tool with manual placement. Typography and styling control is limited. Rendering differs slightly between environments, so a diagram that looks right on GitHub may not in a PDF pipeline. And it covers a fixed set of diagram types — anything outside them is not expressible.
Verdict. Adopt it for documentation, README diagrams, and any flowchart describing something that will change. Skip it for publication figures and for complex diagrams where layout is part of the meaning. The condition that flips the answer is simple and practical: when you have spent an hour fighting the auto-layout, that hour was the signal to switch tools.
Common questions
Is Mermaid free?
Yes — free and open source under the MIT licence. A commercial hosted editor exists for teams, but the language, renderer, and all the integrations that matter are free.
Does GitHub render Mermaid diagrams?
Yes, natively. Put your diagram in a fenced code block labelled mermaid in any Markdown file and GitHub renders it — no image files, no uploads, no plugins. GitLab, Obsidian, and most documentation systems do the same.
Can I use Mermaid for journal figures?
Generally not. Auto-layout, limited typography control, and no LaTeX support mean it will not meet a figure specification. Draft the structure in Mermaid if it helps, then rebuild it in Inkscape or TikZ for submission.