This walkthrough covers a build-time setup, the CLI, and where the approach breaks down.

Why render Mermaid at build time?

Because a diagram stored as text diffs cleanly in pull requests. A reviewer sees B -- Yes --> C change, not a binary blob. That single property is why teams move off exported images. Mermaid files are a few hundred bytes and review like code.

How do I install the Mermaid CLI?

The @mermaid-js/mermaid-cli package wraps Mermaid in Puppeteer and converts .mmd files into SVG, PNG or PDF.

npm install -g @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.svg -t dark -b transparent

That mmdc command is the workhorse. Flags worth knowing: -t for theme (default, dark, forest, neutral), -b for background, -w to force width. On a machine without a display, pass -p puppeteer-config.json so Chromium runs headless.

How do I wire it into CI?

Run mmdc in a GitHub Actions step before your docs deploy. Keep one .mmd per diagram in a diagrams/ folder.

1. Commit source .mmd files.
2. In CI, run mmdc to regenerate SVGs into static/.
3. Fail the build if rendering throws — broken syntax never ships.

Step 3 matters more than it looks. Mermaid fails silently in some renderers, producing a blank box. Running it in CI catches that before readers do.

Mermaid vs a canvas diagram tool: which fits?

The honest trade: Mermaid wins on maintenance, canvas tools win on looks. For architecture docs that change monthly, Mermaid is the better bet. For a pitch deck, it is not.

What are the common pitfalls?

Three show up again and again. First, special characters in labels — quotes and parentheses — break parsing unless escaped. Second, the default theme fonts differ from your site, so text size shifts between environments. Third, large sequence diagrams with 20+ actors become unreadable; split them into two diagrams instead of scaling down.

There is no official paywall here. The CLI is MIT-licensed, and the Puppeteer download is roughly 300 MB on first install — budget for that in CI caches.

Quick Summary

• Build-time rendering keeps diagrams in sync and reviewable in pull requests.
• The Mermaid CLI (mmdc) converts .mmd files to SVG, PNG or PDF.
• Run it in CI and fail the build on syntax errors to catch blank renders.
• Trade-off: Mermaid favors maintainability, canvas tools favor visual control.

The catch most people hit early: Mermaid is a tool, not a website. You need somewhere to run it. Below is the fastest path, plus the versions and limits worth knowing in 2026.

What is Mermaid and what does it actually do?

Mermaid is a text-to-diagram renderer. You write code like A --> B and it produces a clean SVG. It powers diagram blocks in GitHub, Notion, Obsidian, GitLab, and the official Mermaid Live Editor. Because output is SVG, the diagrams stay sharp at any zoom level and can be committed to Git alongside your code.

It supports around 15 diagram types today. The ones you will use most: flowchart, sequence, class, state, ER, pie, and gantt.

How do I render my first Mermaid diagram?

The Mermaid Live Editor is the fastest option — open it in a browser, paste, done.

1. Go to the Mermaid Live Editor (mermaid.live).
2. Paste this in the left pane:

flowchart TD
    A[Start] --> B{Logged in?}
    B -- Yes --> C[Show dashboard]
    B -- No --> D[Show login]
    D --> A

3. Watch the right pane render instantly. Switch to the Code tab to copy the SVG or PNG for a doc. The whole thing takes about 90 seconds once you know where to click.

Is Mermaid free to use?

Yes. Mermaid is released under the MIT license and costs nothing, even commercially. The Live Editor is hosted free by the maintainers. The only real cost is your time learning the syntax — and that is small compared to drawing tools.

How do I embed Mermaid in Markdown or GitHub?

GitHub, GitLab, Notion and Obsidian all render Mermaid natively. Wrap the syntax in a fenced block tagged mermaid:

```mermaid
sequenceDiagram
    Alice->>Bob: Deploy to prod
    Bob-->>Alice: Done in 4m
```

On GitHub, this renders on save. Same for GitLab and Notion. Obsidian needs the file saved as .md and the diagram block recognized — it works out of the box in current versions.

Where does Mermaid fall short?

Auto-layout is Mermaid’s weak spot. Complex graphs with 30+ nodes often produce tangled lines, and there is no drag-to-reposition — you fight the layout with invisible spacing hacks. If you need pixel-perfect control, a canvas tool fits better.

Best for: engineers documenting architecture, teams keeping diagrams in Git, and anyone who wants version control on their visuals. Not for: marketing decks that need custom branding and manual placement.

Quick Summary

• Mermaid renders flowcharts, sequence diagrams and Gantt charts from plain text; MIT-licensed and free.
• The fastest start is mermaid.live — paste code, copy the SVG.
• GitHub, GitLab, Notion and Obsidian render it natively with a “`mermaid fence.
• Weakness: automatic layout gets messy past ~30 nodes; no manual repositioning.