Mermaid drill-down links

How to make diagram nodes clickable. For the diagram style and layout rules, see conventions/mermaid-style.

Mermaid — drill-down links

Make diagram nodes navigable. Mintlify honors Mermaid’s click directive: each node gets a pointer cursor, a hover tooltip, and navigates on click. This is the canonical way to get “zoom in to a detail page” behaviour on this site — no custom components, no SVG export, no JavaScript.

When to add clicks

Add click whenever a node represents a topic that has its own detail page on this site or its own canonical external URL (a repo, a dashboard, a vendor doc). This is the default for context, overview, and hub diagrams — not an optional embellishment. Skip clicks for: nodes that don’t map to a real destination (a transient process, an abstract concept like “Code” or “Ship”), or destinations that are still TODO and would 404.

Canonical syntax — INTERNAL links only

Use only this form. One click per line. Always include a tooltip — for hover-only users it’s the only signal of where the click goes.

click NodeId "/path/to/internal/page" "Short hover tooltip"

Place the click block AFTER all classDef definitions and class assignments, and BEFORE any linkStyle lines.

External URLs — do NOT click them from the diagram

Mermaid has open bugs (#3077, #5550) where _blank is parsed but silently dropped from the rendered SVG. Clicking an external link on a node navigates the current tab away — the diagram disappears, the back button is the only way home. Workaround: put external links in a table or CardGroup directly under the diagram. Mintlify automatically adds target="_blank" rel="noreferrer" to external markdown anchors, so those open in a new tab correctly. Inside the Mermaid block, click ONLY the internal nodes; leave the external-pointing nodes without a click directive and add an HTML comment naming where the repo lives:

flowchart LR
  Tool([Tool]) --> Pack([cc-edge-foo])
  click Tool "/observability/overview" "Tool overview"
  %% No click on Pack — external repo lives in the table below.

Then the table directly under the diagram carries the external link:

| Repo | Notes |
| --- | --- |
| [cc-edge-foo](https://github.com/owner/cc-edge-foo) | What it does |

When the Mermaid bugs are fixed upstream, this convention will expand to allow external clicks; until then, internal-only.

Self-check addition

Append these to the existing self-check before emitting any context, overview, or hub diagram:

Every node whose label names a topic with a detail page has a click line
All click URLs are site-relative paths (/security/overview), never external https://...
External repo URLs live in a table or CardGroup beside the diagram, NOT in click directives
Tooltips are ≤40 chars and describe the destination (not the node)
No click points at a page that doesn’t exist yet (would 404)
CI Mermaid validation passes (./scripts/validate-mermaid.sh from repo root)

Example

flowchart LR
  Ovr([Overview]) --> Detail([Detail page])
  classDef hop fill:#102937,stroke:#4FB3A9,stroke-width:2px,color:#F4EFE6;
  class Ovr,Detail hop
  click Ovr "/overview" "Read the full overview"
  click Detail "/overview/detail" "The deep dive"

When NOT to use clicks

Pure sequence / timeline diagrams where every node is a stage in one flow (e.g. CI step “Lint”) — clicks would imply each stage has its own page when the whole pipeline is one page.
Diagrams in repo READMEs that render on GitHub. GitHub’s Mermaid renderer honors click differently and absolute URLs are required there. Keep site-relative click diagrams on docs.jacobpevans.com; if a README needs an interactive diagram, link out to the relevant docs page instead.