author-mermaid-diagram

name	author-mermaid-diagram
description	Use when adding or fixing a mermaid diagram in a Hugo (or other static-site) page so it renders readably inline in a narrow content column (triggers "add a diagram", "mermaid", "diagram is too wide"). Covers the width rule, layout direction, the semantic color palette, and the browser viewBox check.

Authoring Mermaid Diagrams

Most static-site themes render mermaid from a ```mermaid fence or a {{< mermaid >}} shortcode; the constraints below are the same everywhere.

Width Rule

The critical constraint: the content column is typically ~800 px, so a diagram whose natural (viewBox) width exceeds ~900–950 px shrinks until its text is unreadable inline. Keep every diagram under ~900–950 px natural width.

Measure in a browser after hugo server:

document.querySelector('.mermaid svg').viewBox.baseVal.width

Design choices that keep diagrams narrow:

• Prefer flowchart TB (top-to-bottom) over flowchart LR (left-to-right).
• ≤3 nodes per rank.
• ≤4-word edge labels.
• ≤12 nodes per diagram — split larger ones.
• Avoid side-by-side subgraphs: the direction attribute on a subgraph is ignored when its nodes have external edges, so paired subgraphs force a wide layout regardless.

Diagram Type Choice

Type	Use for
flowchart TB	Component/data flows (default)
sequenceDiagram	Request/interaction ordering between actors
stateDiagram-v2	Lifecycles (states and transitions)

For sequenceDiagram: use autonumber, keep to ≤4 participants, use short participant names. Do not use classDiagram — it exceeds the width rule and is seldom the right tool for documentation flows.

Step Numbers on Arrows

Label numbered steps as -->|"<b>1.</b> description"| — the <b> renders bold via the project's stylesheet. Never use circled glyphs (①②③). sequenceDiagram uses autonumber instead of manual labels.

Palette — color nodes by semantic role

A single-color theme hides meaning in flow/sequence diagrams. Apply a small semantic palette via classDef so role reads at a glance in light and dark mode. Mid-tone Tailwind 400/500 fills with white text:

Class	Use for	Fill	Stroke
leader	Active / primary actor	#10b981	#047857
standby	Passive / waiting	#94a3b8	#475569
lease	Coordination primitive (lock, lease, bucket)	#f59e0b	#b45309
resource	Resource being acted on	#fb7185	#be123c
external	External system (API, gateway)	#64748b	#334155
process	Logic / decision / generic step	#38bdf8	#0369a1

All classes use color:#fff. Rules:

• Only declare the classes a diagram needs.
• Once you class one node, class every node (mixing classed and unclassed nodes looks broken).
• Append classDef and class lines at the bottom of the diagram body, before the closing fence/shortcode.
• Inside a subgraph, put the classDef/class lines after the matching end.

Theme notes

Theme-specific gotchas (verify for yours):

• Docsy caches partials: after editing body-end.html (or any hook partial), restart hugo server — live reload serves the stale partial.
• Lightbox keeps SVG ids: the click-to-zoom lightbox clones the SVG and scopes its embedded CSS to the original id. Do not strip ids from mermaid output.

Diagrams must be readable inline without clicking — the lightbox is a bonus, not a substitute for a well-proportioned diagram.

Common Mistakes

Mistake	Symptom	Fix
Used flowchart LR with many nodes	Diagram overflows the column, text unreadable	Switch to flowchart TB or split the diagram
Subgraph direction LR with external edges	Layout ignores direction, still wide	Restructure — avoid subgraphs with external edges
Edited a hook partial without restarting server	Lightbox / theme change not visible	Restart hugo server
Stripped SVG ids	Lightbox shows unstyled diagram	Keep the mermaid-generated SVG id
Single giant diagram > 12 nodes	Too dense, overcrowded	Split into focused smaller diagrams