Search highlights (<mark>) cleared within milliseconds, invisible to users

[cderv]

Tip

Demo website: https://cderv.github.io/quarto-search-highlight-demo/

When navigating to a page via search (with ?q= parameter), the highlight() function adds <mark> elements around matching text. These marks are then cleared almost immediately (~24ms on quarto.org) by quarto-hrChanged events, making them invisible to users.

Steps to Reproduce

1. Go to any Quarto website page with ?q=someterm (e.g. html-basics.html?q=format)
2. Observe that no highlighted text is visible

Instrumented testing on quarto.org shows marks appear and disappear within a single frame:

404ms: 17 <mark> elements added by highlight()
428ms: 0 <mark> elements — all cleared by resetHighlighting()

Root Cause

The clearing chain:

1. quarto-search.js registers a one-shot listener for quarto-hrChanged that calls clearHighlight():
   https://github.com/quarto-dev/quarto-cli/blob/aaaba63c2/src/resources/projects/website/search/quarto-search.js#L67-L76

2. quarto-nav.js dispatches quarto-hrChanged from updateDocumentOffset():
   https://github.com/quarto-dev/quarto-cli/blob/aaaba63c2/src/resources/projects/website/navigation/quarto-nav.js#L196-L197

3. updateDocumentOffset() is triggered during initial layout settling by a ResizeObserver on the header element and a setTimeout(250):
   https://github.com/quarto-dev/quarto-cli/blob/aaaba63c2/src/resources/projects/website/navigation/quarto-nav.js#L254-L269

The comment says "Clear search highlighting when the user scrolls sufficiently", but the event fires from layout recalculation, not user interaction.

Context

PR #14003 added text fragments (:~:text=) to search result URLs, which provides browser-native scroll-to-text highlighting that persists independently. This effectively works around the broken <mark> behavior for visible text, but text fragments cannot highlight content inside hidden elements (e.g. inactive Bootstrap tab panes).

Possible Fix

Delay the quarto-hrChanged/quarto-sectionChanged listener registration to skip initial layout settling events, or gate the clearing on actual user interaction (scroll, click).

[mcanouil]

For reference:

• Auto-focus Algolia search box on page load when there's a query parameter #13123

[cscheid]

Between now and release, can we mark all "default" issues to 1.10?

[cderv]

While investigating this fix, I tested the interaction between JS <mark> highlights (?q=) and browser text fragments (:~:text=, added in #14003), building on observations from #13123.

The two mechanisms serve different purposes:

• <mark> highlights all matches on the page (useful on long pages, as noted in Auto-focus Algolia search box on page load when there's a query parameter #13123)
• :~:text= scrolls to and highlights one specific match (browser-native)

On fuse.js sites, they conflict: highlight() wraps text in <mark> tags, and this DOM mutation destroys the browser's text fragment highlight. Even with replaceState() blocked, the DOM mutation alone kills the text fragment. replaceState() then also strips :~:text= from the URL as collateral (since new URL(window.location) can't see text fragments).

On Algolia sites (e.g. quarto.org), there's no conflict because ?q= is only added by fuseSearch(), not the Algolia path — though this is a configuration gap rather than a fundamental difference (#13123).

The fix in #14049 addresses the <mark> clearing. The text fragment conflict is a separate pre-existing interaction.

[vezwork]

See #9802