Badge and preview tmux commands, options, hooks and format variables

[tony]

tmux commands, options, hooks and format variables now render like API mentions: a kind badge, the name, a hover card from the pinned tmux manual, and a link into that manual.

On the Rust page Server, session, window, pane, list-clients was a plain link beside [S] Client, and session_attached and destroy-unattached were not linked at all, though the tmux manual documents both. This covers "Native tmux concepts" (P0 15) and "tmux command interlinking across ports" (P0 18).

Before and after

Before (deployed site)	After (this branch)

Dark theme, and the hover card for destroy-unattached:

Dark	Hover card

The screenshots live on tmux-mention-badges-screenshots, a branch that holds only these four files; delete it after review. "Before" is the deployed site. "After" is a local dev server on the Rust port. A port-scoped build does not serve /tmux/ pages, so the card's JSON came from the real preview endpoint code through a local static server, and the page's own preview script rendered it.

What readers get

Four kinds, named so a tmux catalog can share them:

Kind	Badge	Example	Destination
command	$	list-clients	/tmux/latest/manual/list-clients/
format	#	session_attached	/tmux/latest/manual/full/#session_attached
option	o	destroy-unattached	/tmux/latest/manual/full/#options-destroy-unattached
hook	h	session-created	/tmux/latest/manual/full/#hooks-session-created

• Badge. A lone mention renders with the same api-link-kind api-nav__kind api-badge--kind-* markup as an API mention, so badge spacing, underline and alignment changes apply to both. The four kinds join the badge palette in the light, system-dark and explicit-dark themes.
• Hover card. Command pages preview their manual summary, syntax and alias. The full manual previews each option, hook and format variable by anchor, using the existing fragment lookup. Every card offers "Open manual".
• Markdown and LLM exports. The links match the HTML. Markdown keeps a plain link and carries no badge glyph or markup.

Format variables, options and hooks come from the pinned manual for each release (3.2a and 3.7c), using the same anchors the full manual page renders. A name the release does not document is not linked.

Detection rules

Options, hooks and format variables link only inside code, where a name is deliberate:

• Options and hooks link when hyphenated (remain-on-exit, pane-died).
• A format variable links when it is the whole span, or sits inside a #{...} expression, quoted or not.
• These stay plain: mouse, pid, tmux://panes/{pane_id}, capture_pane(pane_id), --destroy-unattached, and a name inside a path or flag.
• A library symbol outranks an option, hook or format variable in HTML, prose Markdown and symbol Markdown. session_name on the Rust page still reaches its Rust field, and session_attached goes to tmux.
• Several names in one code run, such as tmux set-option -g destroy-unattached on, become separate links with no badges, so the run keeps its code flow.

One resolver

tmuxEntityHref(kind, name, version) in tmux-links.ts is now the only place a tmux name becomes a destination, including commands. It returns the manual anchor today and nothing for an unknown name. The catalog work can change its body to point at catalog routes.

Coverage

Measured by rendering every Markdown page under site/src/content/docs through the real pipeline (440 pages; MDX pages are not counted), and every API doc comment through the same linker the reference pages use.

	Before	After
Guide and port prose: tmux links	349	590
of which badged	0	453
of which options, hooks, format variables	0	241
API doc comments: tmux links	512	862

The 15 section links in the "before" total are authored links to manual sections. The 137 unbadged links after are those 15 and 122 mentions inside multi-name code runs.

Verification

• The full site suite passes. In one run, the Go prebuild test and the port runtime and staging suites failed while the host was heavily loaded and its servers were being killed; each passed on rerun, and the Go prebuild test also passes on trunk.
• pnpm run lint: no new warnings. pnpm run type-check: 0 errors.
• node scripts/check-api-links.mjs and node scripts/check-nav.mjs pass.
• New tests in site/test/tmux-mentions.test.ts (plus one card test in link-preview.test.ts) cover a command, a format variable, an option and a hook, the hover-card data, the badge classes shared with API mentions, the palette in all three themes, Markdown agreement, API precedence, and unknown names with a linked control. All 43 fail on origin/main.
• native-prose-ownership.test.ts and port-prose.test.ts now allow a native tmux page to link session_name and similar names to the manual, and still reject library links.

Not run: the timed pnpm test loops (the host was too loaded to meet their budgets), the publication audit and its browser matrix, and the assembled-site check-links.mjs --all. The new anchors are covered by a unit test that resolves every entity in the rendered manual.

Notes

• link-preview-paint.ts now treats /tmux/<version>/manual/<command or full>/ as preview targets, and skips the command index list and mandoc heading permalinks.
• tmux-manual.ts loads the highlighter only when it highlights the manual, so link resolution no longer imports it. linkTmuxManualTree exposes the existing anchor pass for the entity data.
• Key tables are not linked. The manual has no anchored entries for them, and prefix is also an option.

[tony]

Folded into #157, which now carries every fix from the 2026-10-18 review on one branch so they share one CI run, preview and deploy. This commit is on that branch unchanged. Discussion and evidence stay here.