Overview
Mermaid turns indented text into flowcharts, sequence diagrams, Gantt charts, and more — inside Markdown. Because GitHub, GitLab, Obsidian, and most doc systems render it natively, the diagram source lives next to the code it documents and diffs like everything else.
Why researchers use it
- Version-controlled diagrams — text sources diff and review like code
- Rendered everywhere — GitHub READMEs, Obsidian notes, Hugo sites
- Fast iteration — restructure a flowchart by editing lines, not dragging boxes
Getting started
- Try the live editor at mermaid.live with a flowchart: graph TD; A–>B.
- Drop the same block into a GitHub README inside ```mermaid fences.
- Theme it once per project — this site’s identity kit includes a Mermaid theme config.
The honest review
Strengths. The maintenance story: when the pipeline changes, you edit five lines of text and every rendered copy updates. Perfect for methods flowcharts in repos and documentation.
Limitations. Layout is automatic and only somewhat steerable — complex diagrams become spaghetti you cannot untangle by hand; fine visual control is not the point.
When NOT to use this
Publication figures needing exact layout and typography belong in TikZ or Inkscape — when you fight Mermaid’s auto-layout for an hour, that was the signal to switch.