Produce diagrams that are correct, legible in print, and consistent as a set — not just syntactically valid Mermaid.
The one non-negotiable rule
Never trust unrendered diagram code. Mermaid layout is emergent: label widths, edge routing, and subgraph sizing only exist after rendering. The loop is:
- Author the
.mmd - Render it:
scripts/render-mmd.sh diagram.mmd - Look at the preview image (the script writes a
*-preview.pngsized for inspection) - Fix clipping, overlaps, label collisions, edge crossings — re-render
- Repeat until clean (minimum one fix round; diagrams are never right first try)
A diagram you haven't looked at is a draft, not a deliverable.
Workflow
- Purpose first. One diagram, one purpose, one audience. Write the 5-second story the reader must grasp (what talks to what, through what, where the boundaries are) before drawing. If a diagram needs two stories, make two diagrams.
- Pick the flow direction. Topology/containment reads top-down (
TB); pipelines read left-to-right (LR) — but for print/PDF destinations, tall-and-narrow TB beats wide LR: an LR pipeline scaled to text width prints at ~4–5pt. Verified repeatedly. - Apply the design system. Use the semantic tokens, edge grammar, and label rules in DESIGN-SYSTEM.md. Color means something or it isn't used. Default to the glass + elevation look (Look 2, judged 8/10); the flat look (5/10) is the exception — reach for it only when colorblind-safety or compliance is explicitly required. "Unknown audience" or "just show me X" is a Look 2 case. See DESIGN-SYSTEM.md's decision rule; don't pick flat because it's listed first.
- Author within the verified allowlist. TECHNIQUES.md contains only constructs verified through real render pipelines, each tagged with where it works. The headline trap: never set
themeVariables.fontFamilyfor Quarto-destined diagrams — it clips every label. - Render with the destination's pipeline (table below).
- Self-review adversarially against REVIEW-CHECKLIST.md — legibility, design consistency, comprehension/correctness. Fix and re-render.
- High stakes? Run a variant competition (sketch in REVIEW-CHECKLIST.md): several styled variants, adversarial judging, recombine winners.
Which pipeline renders the truth?
Preview with whatever will render the diagram in production — otherwise you are tuning against the wrong engine:
| Destination | Render with | Notes |
|---|---|---|
| Quarto / pandoc document (PDF, docx) | render-mmd.sh -p quarto |
The document's own engine; what you see is what ships |
| GitHub README / wiki / GitLab | render-mmd.sh -p mmdc |
mermaid-cli tracks current Mermaid, closest to GitHub's renderer |
| MkDocs / Docusaurus / Hugo site | The site's own build; fall back to mmdc for quick iteration |
Site plugins pin their own Mermaid versions |
| Slides, standalone images | mmdc (-o out.svg for vectors) |
render-mmd.sh auto-detects (-p auto, the default): prefers Quarto when installed, falls back to mermaid-cli. Both paths produce a full-resolution PNG plus an inspection preview.
Engine reality check
Quarto bundles its own Mermaid (e.g. 11.6.0) with its own screenshot machinery; mmdc ships current Mermaid (e.g. 11.12). Same major version — different behavior: parser strictness, font handling, and theme defaults all differ. That is why TECHNIQUES.md tags every construct [universal], [quarto], [mmdc], or [version-sensitive], and why the portable strategy is to author inside the intersection: full classDef tokens (never rely on theme defaults), no fontFamily override, filters via themeCSS not classDef, subgraph titles ≤24 characters. Diagrams written that way render near-identically in both pipelines.
When you meet a new pipeline (different SSG, different Mermaid version), spike it first: render TECHNIQUES.md's probe snippets through it and note divergences before authoring real diagrams.
Bundled references
- DESIGN-SYSTEM.md — semantic color tokens (colorblind-safe default palette), edge grammar, layout, label and legend rules
- TECHNIQUES.md — verified syntax allowlist with pipeline tags, gotcha table, probe snippets
- REVIEW-CHECKLIST.md — adversarial self-review lenses + the variant-competition pattern
- scripts/render-mmd.sh — adaptive render + preview loop (Quarto or mermaid-cli)