> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jacobpevans.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mermaid drill-down links

> Make diagram nodes navigable on docs.jacobpevans.com using Mermaid's click directive: when to add clicks, canonical internal-link syntax, the external-URL workaround, and the self-check.

How to make diagram nodes clickable. For the diagram style and layout rules, see
[`conventions/mermaid-style`](/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.

```text theme={null}
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](https://github.com/mermaid-js/mermaid/issues/3077),
[#5550](https://github.com/mermaid-js/mermaid/issues/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:

```text theme={null}
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:

```text theme={null}
| 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

```text theme={null}
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.