How to Use Mermaid Diagrams in Your Docs Workflow

If you already know Mermaid syntax, the next problem is keeping diagrams alive as code changes. Hard-coded PNGs go stale in weeks. Rendering Mermaid at build time fixes that — your diagram files live in Git and update with every commit.

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?

Need	Mermaid	Canvas tool (Figma, draw.io)
Version control	Yes, full text diff	No, binary files
Manual placement	No	Yes
Custom branding	Limited themes	Full control
Auto-updates in CI	Yes	Manual

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.