Skip to main content
Showing everything shows nothing. One diagram per concern, kept in sync with the code, beats one giant chart no one reads.
Required for any repo with meaningful architecture. Stale diagrams are worse than no diagrams — they actively mislead. The rules below cover format, placement, and what to draw.

​
Format

  • Inline fenced mermaid blocks in Markdown — GitHub renders them natively, Mintlify renders them on the docs site
  • Standalone .mmd sources in docs/assets/ when the diagram is referenced from multiple pages or needs to render outside Markdown
  • Render to SVG with nix run nixpkgs#mermaid-cli -- -i x.mmd -o x.svg

​
Placement

​
What to draw

  • System overview for the repo as a whole
  • Cross-repo context when the repo’s outputs feed other repos’ inputs
  • One diagram per major data flow — do not collapse. If two flows are tangled enough to need two diagrams, they are tangled enough to need two diagrams
  • Sequence diagrams for multi-party flows (auth, API chains, CI pipelines)
  • Component or deployment diagrams for non-trivial topology

​
Style

The canonical Mermaid style guide for the docs site lives in conventions/mermaid-style, with node-navigation rules in conventions/mermaid-links. The byte-for-byte theme directive, shape vocabulary, semantic classDef palette, indexed linkStyle palette, and the four narrative shapes (linear chain, parallel convergence, hierarchy, hub and spokes) are reusable across every repo that publishes diagrams alongside its code. Highlights:
  • One narrative shape per diagram — never combine
  • Subgraphs only for things that physically or logically co-locate (a cluster, a host, a network); never for roles or phases
  • Max 5 nodes per rank, 5 nodes per subgraph, 12 nodes per diagram
  • Every edge crosses at most one subgraph boundary
  • Use classDef for grouping, never per-node style
  • Color edges by semantic category via indexed linkStyle, never by linkStyle default

​
When not to use Mermaid

If the content is a flat list, a comparison, or sequential steps without branching, prefer a table or <Steps> component. Mermaid is for shapes; tables and Steps are for everything else.

​
What this connects to

Architecture overview

The canonical examples of every narrative shape in production use.

How it fits together

A single linear-chain diagram doing the work of three text pages.

Security · how it fits together

Multiple diagrams, one per concern — the pattern in action.