Also show code callouts as tooltips

[florent-leborgne]

In case of long code blocks with callouts, it'd be super handy to have tooltips on callout numbers that include the text of the callout.

Here is an example of a long code block. Instead of scrolling, the user could just hover over each callout and read what it means.

[theletterf]

+CC @itsalexcm

[cotti]

AI triage

Automated investigation against the current codebase. A human still needs to confirm before any code change.

Original concern

Code callout numbers in code blocks should also expose the callout text as a tooltip on hover, so readers don't have to scroll to the list below long blocks.

Findings

• src/Elastic.Markdown/Myst/CodeBlocks/EnhancedCodeBlockHtmlRenderer.cs:73-83 — callout markers are emitted as <span class="code-callout" data-index="{Index}"></span>. The marker only carries the numeric Index; the callout text is not attached to it.
• src/Elastic.Markdown/Myst/CodeBlocks/CodeViewModel.cs:59-62 — the console/apiheader rendering path emits the same data-index-only marker, so a fix would need to touch both render spots.
• src/Elastic.Documentation.Site/Assets/markdown/code.css:32-38 — the visible number comes purely from CSS content: attr(data-index). There is no title attribute and no hover/tooltip/popover wired to these markers today.
• src/Elastic.Markdown/Myst/CodeBlocks/CallOut.cs:10 — the callout Text already exists in the model, and EnhancedCodeBlockHtmlRenderer.cs:212-269 renders it (as Markdown) into the <ol class="code-callouts"> list below the block. So the data is available; it just isn't surfaced on the marker.
• src/Elastic.Documentation.Site/Assets/web-components/AppliesToPopover.tsx:128-151,340-374 — a reusable hover-popover pattern already exists (EUI EuiPopover, 250 ms hover delay, touch-device detection, keyboard/role="button" a11y). A rich callout tooltip would most naturally reuse this approach rather than a native title.
• No partial work found: git log --all -S "code-callout" / --grep="tooltip" shows callout rendering history (e.g. Render inline Markdown in automatic callouts and update docs #3324, Render callouts in code block #346) but nothing adding hover tooltips to markers.

Verdict

Needs stakeholder input

The data needed (callout Text) is already on the model, and the markers are a single, well-defined element — so this is technically feasible. But "show callouts as tooltips" hides a design fork: a minimal native title would only show plain text (callouts support Markdown/links, so formatting and links would be lost), while matching the issue's screenshot implies a rich popover that brings cross-device (touch/mobile), accessibility, and "do we still keep the list below?" decisions. Those are UX/product calls, not a mechanical edit, so I'd route this for input before implementation.

Proposal

Questions for UX/product (ai:ux-question)

• Plain-text native title tooltip vs. a rich popover (formatted Markdown, links)? The author's example suggests rich.
• Should the list below the block remain when tooltips are added, or only on small/long blocks?
• Touch/mobile behavior: tap-to-pin like AppliesToPopover, or hover-only (desktop)?

Questions for engineering (ai:eng-question)

• If plain text: pass CallOut.Text through as a title/data-text attribute at the two render spots (EnhancedCodeBlockHtmlRenderer.cs:73-83 and CodeViewModel.cs:59-62) — small change.
• If rich: render callout Markdown into the marker (or a data-*/template), then reuse the AppliesToPopover.tsx hover/touch/a11y pattern for the code-callout marker — larger change spanning C# render + a new frontend web component.

Related issues

• [Feature Request]: working links inside code blocks #1321 (open) — working links inside code blocks; adjacent "richer interactions in code blocks" theme, not a duplicate.
• [Feature Request]: Add in-context annotations and discussions #2381 (open) — in-context annotations and discussions; different feature, only thematically related.

Notes

No existing tooltip/hover behavior on callout markers, so this is net-new UI rather than a regression. If UX prefers the minimal route, the plain-text title variant is a genuine quick fix; the rich-popover variant is not.