diagram trained

mental model

Destination chooses the diagram: Mermaid keeps source reviewable in a document, Excalidraw keeps a canvas editable, SVG is a stable publishable artifact, and preview inspects an existing artifact. Draw from source, then render before calling a diagram complete.

examples

flowchart LR
  browser[Browser] --> api[API]
  api --> store[(Store)]

Use Mermaid's documented configuration rather than a remote script or invented renderer contract. Official source

best practices

State the reader question and evidence source before drawing.
Use one directional flow and short, semantic edge labels.
Render SVG/PNG to check collisions, clipping, and contrast. HTML diagrams, reports, and demos use only MonoLisa Nerd Font, MonoLisa, then monospace.

strengths

Mermaid travels with Markdown, Excalidraw is editable, and SVG is portable.

weaknesses / pain points

Large diagrams become unreadable quickly and can falsely imply authority when labels are not source-backed.

gotchas

Mermaid configuration has security and rendering consequences.
Parsing an SVG does not prove a readable render.

known bugs

No version-specific defect is recorded. Add upstream issue and library release only after reproduction.

troubleshooting

symptom	root cause	fix
reader cannot follow flow	multiple directions compete	choose one primary direction
export clips labels	dimensions came from source, not render	enlarge viewBox and re-render
diagram drifts from code	it was drawn from recollection	trace current owners and redraw

practiced cases

mermaid cli 11.12.0 accepted a three-node flowchart but could not render it: chrome headless shell 131.0.6778.204 is absent from the configured puppeteer cache, so no output artifact was made.
rsvg-convert rendered a 320 x 120 MonoLisa-labelled SVG to PNG, which confirms the standalone SVG validation path.

Read diagram for the full guru: routing, formats, and examples.