why: Verify the sphinx-gp-mermaid renderer on the live site — the
production path runs behind Cloudflare (Rocket Loader), which local
builds cannot reproduce.

what:
- Add mermaid to the docs workflow's push trigger
- Force PUBLISH on the mermaid ref so a workflow-only push deploys

Revert this commit before merging #1073.

why: Verify the sphinx-gp-mermaid renderer on the live site — the
production path runs behind Cloudflare (Rocket Loader), which local
builds cannot reproduce.

what:
- Add mermaid to the docs workflow's push trigger
- Force PUBLISH on the mermaid ref so a workflow-only push deploys

Revert this commit before merging #1073.

why: Verify the sphinx-gp-mermaid renderer on the live site — the
production path runs behind Cloudflare (Rocket Loader), which local
builds cannot reproduce.

what:
- Add mermaid to the docs workflow's push trigger
- Force PUBLISH on the mermaid ref so a workflow-only push deploys

Revert this commit before merging #1073.

Adds `sphinx-gp-mermaid`, a workspace package that renders MyST
`mermaid` fences to inline SVG at build time via mermaid-cli.
Diagrams paint with the page — no client-side runtime, no async
pop-in, no layout shift — and follow the site's light/dark theme
with no JavaScript. Extracted from tmuxp's production
`docs/_ext/mermaid_inline.py`; tmuxp adopts the package in the
companion PR.

- **Dual-theme, zero-JS**: each diagram renders to a light and a
  dark SVG matched to the gp-furo palette, inlined and toggled by
  CSS on the page theme. Mermaid bakes id-scoped `!important`
  colors into its output, so a single render cannot follow the
  toggle.
- **Content-addressed cache**: rendered SVGs are cached under
  `<confdir>/_mermaid_cache`, keyed on render version, theme,
  config, and source; the cache survives clean builds and writes
  atomically so parallel writers never read a torn SVG.
- **Graceful degradation**: a missing or failing renderer warns
  once per builder and falls back to the diagram source, keeping
  `:name:` anchors intact; non-HTML builders emit an alt-text
  stand-in instead of crashing.
- **Conf-level fence routing**: `merge_sphinx_config()` routes
  plain ```mermaid fences to the directive when the extension is
  active; explicit overrides still win.
- **Opt-in**: not in `DEFAULT_EXTENSIONS` — rendering needs a Node
  toolchain (mermaid-cli + headless Chrome), so consumers who
  don't use diagrams pay nothing.
- **Documentation**: ships the package's full Diátaxis tree
  (how-to, reference, dependents) and a live example gallery
  showing diverse diagram types as the extension's real
  dual-theme output.

See also: tmux-python/tmuxp#1073

why: Verify the sphinx-gp-mermaid renderer on the live site — the
production path runs behind Cloudflare (Rocket Loader), which local
builds cannot reproduce.

what:
- Add mermaid to the docs workflow's push trigger
- Force PUBLISH on the mermaid ref so a workflow-only push deploys

Revert this commit before merging #1073.

why: Verify the sphinx-gp-mermaid renderer on the live site — the
production path runs behind Cloudflare (Rocket Loader), which local
builds cannot reproduce.

what:
- Add mermaid to the docs workflow's push trigger
- Force PUBLISH on the mermaid ref so a workflow-only push deploys

Revert this commit before merging #1073.