Diagrams as Code with Mermaid

Keeping Diagrams Readable and Embedding Them

When a diagram is getting too big

No hard node-count rule exists, but three signals are reliable: the auto-layout produces crossing edges you can't untangle; a new team member spends more than 30 seconds finding the entry point; or you keep adding "context" nodes that don't belong in the diagram's original scope. At that point, reach for one of these moves before fighting the renderer.

Split by audience. An overview diagram introduces the system to someone new; a detail diagram shows one component to someone implementing it. These genuinely serve different readers. Put both in the same Markdown file under separate headings — they complement rather than replace each other.

Split by time horizon. A happy-path diagram and an error-path diagram are easier to read separately than combined with nested alt blocks. The same principle from the sequence diagram submodule applies everywhere.

Split by depth. Draw the top level first — Client → API Gateway → Services. Each service node gets a click directive linking to a second diagram or a fragment anchor in the same doc that expands only that service. Readers drill down on demand; the overview stays clean.

Subgraphs as the middle ground

Before splitting into separate files, try a subgraph. A well-named subgraph communicates ownership without multiplying documents. Naming convention matters more than you'd expect — subgraph auth [Auth Service] is immediately clearer than subgraph sg1. Consistent subgraph IDs across diagrams in the same doc make cross-references easier too.

From the flowchart submodule: nesting subgraphs past two levels almost always signals the diagram should split. Subgraphs at depth three start looking like ASCII art — split instead.

One practical habit: if you're copy-pasting the same cluster of nodes into multiple diagrams just to provide context, that cluster wants to be its own named diagram with a stable link. Reference it, don't replicate it.

Consistent naming across diagrams

In a doc with five related diagrams, use the same node IDs for the same concepts throughout. If AuthSvc is a participant in a sequence diagram, use AuthSvc in the flowchart too — not auth, not AuthService, not A. Readers build a mental map; inconsistent naming forces them to re-map on every diagram.

%% ❌ Three names for one concept — reader must re-map every diagram
%% sequence:  participant auth as Auth
%% flowchart: AuthService[Auth] --> GW[Gateway]
%% ER:        Auth ||--o{ Session : "creates"

%% ✓ One stable ID, one display label — reader maps once and reuses
%% sequence:  participant AuthSvc as Auth Service
%% flowchart: AuthSvc[Auth Service] --> GW[API Gateway]
%% ER:        AuthSvc ||--o{ Session : "creates"

Same rule for display labels: pick one canonical name per concept and commit to it. Short source IDs (AS) are fine as long as the display label is always the full readable name (Auth Service).

Hiding detail behind links

This is where the click directive from the previous submodule earns its keep at scale. An architecture overview doesn't need to show every database column or API route — it needs to link to the diagrams that do. With securityLevel: 'loose' set on your site, every node becomes a navigation point.

For a docs site, relative fragment links work cleanly:

click AuthSvc "#authentication-flow" "See auth sequence diagram"

The reader stays in context; the overview stays clean.

The "should this be two diagrams?" test

If you're hesitating, ask: do these two parts of the diagram have different audiences, different update cadences, or different levels of abstraction? Any "yes" is a split signal. A database schema diagram and a call-flow diagram live in the same system but serve completely different readers — keep them separate even if they share entity names.

---

Embedding on GitHub

On GitHub, the triple-fence with the mermaid language tag is all you need:

````

flowchart LR
    A[User] --> B[API] --> C[(DB)]

````

GitHub renders this natively in README files, issues, pull request descriptions, and wiki pages — no JavaScript, no CDN link, no configuration. The renderer uses a fixed internal Mermaid version that you don't control, which means diagrams can subtly change behavior across GitHub updates. For stable long-lived diagrams this is usually fine; for precise control, your own site is the answer.

Two GitHub-specific limits: click directives are silently dropped (the same security restriction covered in the previous submodule), and complex diagrams occasionally time out and render as a broken image. When that happens, splitting the diagram is the fix — the timeout is a concrete readability signal, not just a renderer quirk.

Embedding on your own site

The current approach uses an ES module import. The full minimal page:

<!DOCTYPE html>
<html>
<body>

<pre class="mermaid">
flowchart LR
    A[Client] --> B[API] --> C[(Database)]
</pre>

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>

</body>
</html>

Three things to know: type="module" is required — the ESM build uses import syntax and won't load without it. Each diagram goes in its own <pre class="mermaid"> block; multiple blocks on the same page all render. And startOnLoad: true tells Mermaid to scan the DOM and render every .mermaid element as soon as the script runs.

mermaid.run() for dynamic content

If diagrams arrive after the initial page load — a single-page app, a lazy-loaded section, content fetched from an API — startOnLoad: true fires too early and misses them. The fix:

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: false });

  // Call this after your dynamic content is in the DOM
  await mermaid.run({
    querySelector: '.mermaid',
  });
</script>

mermaid.run() was added in v10 and is the preferred API for programmatic rendering. It accepts a querySelector to target specific elements. Call it again whenever new diagrams appear — it only processes elements that haven't been rendered yet, so multiple calls are safe.

Version pinning

mermaid@11 in the CDN URL resolves to the latest 11.x release. That gets you patches automatically but also potential layout shifts between minor releases. For production docs, pin to the exact version:

https://cdn.jsdelivr.net/npm/mermaid@11.4.0/dist/mermaid.esm.min.mjs

The current version is always visible on npmjs.com/package/mermaid. When you do update, check the Mermaid changelog before bumping — the rendering engine occasionally changes how it handles edge labels, subgraph direction overrides, or theme variables in ways that shift existing diagrams.

If you use a bundler, install via npm instead:

npm install mermaid@11.4.0

The CDN approach suits documentation sites and small tools well. npm install makes more sense when Mermaid is one of many dependencies in a built project with a lockfile.

---

Quick check

1. Take any diagram from an earlier submodule that has more than eight nodes. Split it into an overview (≤5 nodes, each with a click directive linking to a detail section) and a detail view.

2. Build a minimal HTML page that loads Mermaid from jsDelivr with the full version number pinned, sets securityLevel: 'loose', and renders a diagram in a <pre class="mermaid"> block.

3. Add a mermaid.run() call that re-renders a container after a simulated async load — test it by appending a new <pre class="mermaid"> via setTimeout and then calling mermaid.run().

---

That wraps the course. You now have: flowcharts you can debug from scratch, sequence diagrams for real API flows, class and ER diagrams that track schema changes, state machines and Gantt charts for the temporal view, a full styling toolkit with classDef and themeVariables, and a working embedding setup for your own sites. The skill from here is repetition — draw something from your current project and fix what doesn't render cleanly.