Mermaid Conventions

Write Mermaid diagrams that render cleanly and stay readable, and check every diagram with the Mermaid CLI (mmdc) before it goes into a document, because generated diagrams are often invalid or render as an unreadable strip.

Syntax. Put each statement on its own line. Use commas or separate sentences instead of semicolons in labels, messages, and notes; sequence diagrams treat a raw semicolon as a statement separator and break:

sequenceDiagram
    N-->>D: Unsupported, no handler runs

Layout. Long single-column chains (A --> B --> C --> D …) render tall, thin, and zoomed out, with tiny text. Group steps into subgraphs by phase, system, or owner, and draw independent steps side by side, fanning out and back in, so the diagram gets width to balance its depth: