The worst part of drawing flowcharts isn't drawing — it's changing them. Lucidchart drag-and-drop, Excalidraw rebuilds — every requirement change starts over. **Mermaid describes diagrams in plain text**: version control, git diff, multi-person collaboration — all solved. This guide uses our `mermaid-editor` tool as the worked example, covering syntax for the 7 diagram types, 3 gotchas I've hit, and how it integrates with GitHub / Notion / Confluence.
Why Mermaid replaced half my Lucidchart / draw.io use cases
Plain text vs drag-and-drop differs in the cost of one edit:
- Drag-and-drop: open file → find the box → double-click → edit text → save → re-export PNG → replace the image link in README
- Mermaid: open markdown → change one character → commit
Plus version control wins: git diff shows exactly how the diagram changed — diagram logic gets reviewed at the PR stage. Architecture docs in PNG are "frozen decisions"; in Mermaid they're "living docs."
Mermaid is NOT for: detailed visual design (posters, slide hero visuals), advanced UML (activity diagrams with swim lanes), org charts beyond ~30 nodes.
Which of the 7 diagram types to pick
flowchart: most common. Decision trees, API call flows, processes. flowchart LR is horizontal, TD is top-down.
sequenceDiagram: multi-service interaction. React → API gateway → DB → cache — for microservice chains, sequence is 100x clearer than flowchart.
gantt: project timeline. Set dateFormat YYYY-MM-DD, group via section, express dependencies with after task1. Show your boss directly — no need for Project / Notion timelines.
classDiagram: OOP design. For SDK / framework design with inheritance / interfaces.
erDiagram: database relationships. The standard format for talking to DBAs about schema.
mindmap: brainstorming, article outlines.
pie: percentage visuals. Simple but effective for retros.
GitHub / Notion / Confluence / Obsidian all just work
GitHub (Issues, PRs, Wiki, README): write a ```mermaid code block — GitHub's render engine handles it. Write architecture PRs with the flowchart and code in the same commit — reviewers see everything in one view.
Notion: same mermaid code block (post-2024).
Confluence: use the "Mermaid Macro" or install the Atlas Plugin.
Obsidian: native support — great for technical notes.
Your own site: render with mermaid.js client-side, or generate SVG at build time with mermaid-cli. This tool is the client-side live-render reference implementation.
3 gotchas I've hit
1. CJK node names can break parsing
A[Start server] --> B[Check connection] usually works, but mixed CJK + special chars (、, /, () sometimes confuses the parser. Hit a weird syntax error? Wrap CJK in quotes: A["Start server"].
2. Gantt date formats vary by renderer
Default is dateFormat MM-DD but GitHub may only accept YYYY-MM-DD. When writing project timelines, always declare full year-month-day for cross-platform safety.
3. Browsers crash on huge flowcharts Flowcharts with > 100 nodes take ~2 seconds to render and create huge DOM — mobile browsers may OOM. Fix: split into smaller diagrams (< 30 nodes each), link them via sub-pages.
Advanced: documentation as code
Write Architecture Decision Records (ADRs) in Mermaid under /docs/adr/, reviewed alongside code.
Approach:
- Each ADR is a
.mdfile - Lead with a 2–3 sentence decision summary
- Use Mermaid for the architecture diagram in the middle
- End with "why this choice" + "alternatives considered"
Why it works: 6 months later a new hire onboards, reads git log + the ADRs, and understands why the system is shaped this way. Beats Confluence "decision wikis" because code and docs change together — no drift.
Reference: adr-tools (github.com/npryce/adr-tools), Architectural Decision Records spec.
Writing architecture docs / issue descriptions / project timelines? Live-preview in the Mermaid Editor — rendering is fully client-side, nothing leaves your machine — then drop the ```mermaid block straight into GitHub.