Document search result highlighting for websites (#1927)

* Document search result highlighting for websites

Add new section to website-search.qmd covering highlight persistence, automatic tab activation, cross-element highlighting, and section anchor  support. Add light/dark screenshots and prerelease highlights entry.

* Leverage Lua filter to handle light and dark images

* Add clickable example link for ?q= search highlighting

---------

Co-authored-by: Charlotte Wickham <charlotte.wickham@posit.co>

Author: cderv

docs/prerelease/1.9/_highlights.qmd

@@ -38,6 +38,8 @@ Quarto 1.9 includes the following new features:
 
   - [Use Plausible Analytics](/docs/websites/website-tools.qmd#plausible-analytics): Add privacy-friendly Plausible Analytics to websites via the `plausible-analytics` configuration option.
 
+- [Search Result Highlighting](/docs/websites/website-search.qmd#search-result-highlighting): Improved highlighting of search terms on destination pages, with persistent marks, automatic tab activation for matches inside tabsets, and cross-element highlighting for multi-word searches.
+
 - [`aria-label` for videos](/docs/authoring/videos.qmd#accessibility-label): Improve accessibility of embedded videos by providing custom descriptive labels for screen readers instead of the default "Video Player" label.
 
 - [New `syntax-highlighting` Option](/docs/output-formats/pdf-basics.qmd#syntax-highlighting): Replaces the deprecated `highlight-style` (Pandoc 3.8). Supports style names, custom `.theme` files, `none`, or `idiomatic` for format-native highlighting.

docs/websites/images/search-highlight-tabset-dark.png

@@ -77,6 +77,20 @@ You can use the following `search` options to customize how search results are d
 |                    | ![](images/search-item-context.png){.border fig-alt="search box with navigational context shown above the title of the first result." width="260"}                                                                                |
 +--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
+## Search Result Highlighting {#search-result-highlighting}
+
+When you click a search result, Quarto navigates to the destination page and highlights the matching terms with `<mark>` elements. This works with both the built-in search and [Algolia](#using-algolia) search.
+
+The highlighting is driven by a `?q=` URL parameter. You can manually add `?q=term` to any page URL to highlight occurrences of that term — useful for sharing links that draw attention to specific content.
+
+{{< include /docs/prerelease/1.9/_pre-release-feature.qmd >}}
+
+Highlights remain visible until you navigate away from the page. When a match is found inside a [tabset](/docs/output-formats/html-basics.qmd#tabsets), the correct tab is automatically activated to reveal the highlighted content, including nested and grouped tabsets. Multi-word search terms are highlighted correctly even when they span across formatting boundaries such as bold, italic, code spans, or syntax-highlighted code blocks.
+
+URLs that combine a search query with a section anchor (e.g., `page.html?q=term#section`) scroll to the specified section rather than jumping to the first match. For example, [this link](https://{{< meta prerelease-subdomain >}}quarto.org/docs/computations/execution-options.html?q=%22%23%23%20Heading%202%5Cn%22#raw-output) searches for `"## Heading 2\n"` on the Execution Options page with a `#raw-output` anchor — the Knitr tab is activated (instead of the default Jupyter tab), matches are highlighted inside the code block, and the page scrolls to the Raw Output section:
+
+![](images/search-highlight-tabset.png){.border .include-dark fig-alt="Quarto website showing search result highlighting: the Knitr tab is activated inside a tabset, yellow highlighted marks appear on code lines containing cat statements, and the page is scrolled to the Raw Output section."}
+
 ## Using Algolia
 
 In addition to the built-in search capability, Quarto websites can also be configured to use an external Algolia search index. When rendering a website, Quarto will produce a JSON file (`search.json` in the site output directory) which can be used to update an Algolia index. For more on creating indexes with Algolia, see [Send and Update Your Data](https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/) using Algolia.