Repository navigation
Replace DocSearch with a Lunr search dialog - #215
Open
eric-schneider wants to merge 6 commits into
Open
eric-schneider wants to merge 6 commits into
eric-schneider wants to merge 6 commits into
Conversation
When the site is built with @antora/lunr-extension (which sets env.SITE_SEARCH_PROVIDER), pages load js/vendor/site-search.js instead of the DocSearch script. It renders the same markup DocSearch v3 uses, so the existing DocSearch styles and dark theme apply unchanged, and the navbar button is rendered in the page HTML (no layout shift while scripts load). The script downloads lunr.js and the site's search-index.js only when a reader shows intent to search (hovering or focusing the button, the keyboard shortcut, or opening the dialog), then searches locally. Results are grouped by component and version, with up to three matching sections under each page. Ranking favors title matches over heading matches over body text, as DocSearch's does, requires every query word when some page has them all, tolerates typos, and completes the word being typed. The dialog keeps focus and keyboard handling inside itself, closes on Escape from anywhere and on a plain click of a result, shows an error (and retries) when the index can't load, scopes and validates recent searches, and exposes one labeled listbox per result group. Without the Lunr extension, the Algolia DocSearch integration is used as before.
lunr.Index.load compresses the index's word list into an automaton by merging states that have the same key, and Lunr 2.3.9 builds that key by joining each edge's character and target state id with nothing between them. When words contain digits, two different states can get the same key. Some indexed words then can't be found (jvm11, jvm17, 4151 and 4157 in the full site's index), and a few words that aren't in the index are accepted, which made prefix and typo queries that reached them throw. Override lunr.TokenSet.prototype.toString to end each edge with a comma before the index is loaded. With the full site's index, and with one built from all body text, the automaton then accepts exactly the indexed words, and "jvm17" finds its 7 HCD pages. guardTokenSet, which only caught the errors, is removed.
Contributor
|
UI bundle preview build successful! ✅ |
This comment has been minimized.
This comment has been minimized.
eric-schneider
marked this pull request as draft
October 12, 2026 20:55
The cognitive complexity check that SonarQube runs on the site repository scores two functions here well over its limit of 15: the loop in search() that scores each Lunr result (23) and onModalKeydown() (26). Both were hard to follow, so this splits them up without changing what the dialog does: - Move the title and heading boosts, which repeated the same four-way comparison, into matchBoost(), with each set of factors listed once in TITLE_BOOSTS and HEADING_BOOSTS, and the heading lookup into findHeading() - Move the Tab focus trap into keepFocusInside(), and state when it leaves focus to the browser rather than when it doesn't - Sort the word lists in termRegExp() in their own statements, so it is clear that sort() reorders them in place - Say why the catch blocks around localStorage are empty The file keeps its ES5 style.
Contributor
|
UI bundle preview build successful! ✅ |
This comment has been minimized.
This comment has been minimized.
The search button and dialog drew DocSearch's icons, inline SVG copied from @docsearch/react. Use glyphs from the Lucide icon font instead, which the UI already loads for the theme toggle: file-text, hash, history, corner-down-left, x, search-x, arrow-up, arrow-down and loader-circle. Each glyph fills the same box as the SVG it replaces. - Draw the lines that join a page's matching sections to it in CSS - Show the search button's Ctrl key as text, styled like the dialog's esc key - Remove the DocSearch magnifier SVGs, which were never shown: the button and search bar show the Material Icons magnifier from docsearch.css - Spin the loading icon with CSS, and keep it still for readers who prefer reduced motion The dialog keeps DocSearch's markup and class names, so @docsearch/css still styles it. Keyboard behavior and accessibility check results are unchanged.
Replace the note at the top of site-search.js with a list of the third-party code in the file, in the format of the highlighting bundle's notice: DocSearch 3.7.0 for the dialog's markup and class names, and Lunr 2.3.9 for TokenSet toString(), which fixTokenSetKeys() adapts. Add a notice for each icon font the UI uses, since neither had one: - Lucide (ISC): its font files carry no copyright or license - Material Icons (Apache-2.0): its font files carry only Google's copyright. @fontsource/material-icons-outlined lists OFL-1.1, but Google publishes Material Icons under Apache-2.0, so the notice names that. The notices start with "/*!", so the docs-ui build and the site's Tailwind step keep them when they minify.
Contributor
|
UI bundle preview build successful! ✅ |
This comment has been minimized.
This comment has been minimized.
eric-schneider
marked this pull request as ready for review
October 27, 2026 23:44
Contributor
|
UI bundle preview build successful! ✅ |
|
Build successful! ✅ |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds a search dialog that searches the site's own Lunr index in the reader's browser, for sites built with @antora/lunr-extension.
The dialog reuses the existing search dialog's markup and styles, so it looks the same in light and dark mode and on phones. It downloads Lunr and the index only when a reader goes to search, ranks title matches above heading and body matches, groups results by product and version, tolerates typos, and completes the word being typed. It also fixes a Lunr 2.3.9 bug that made some indexed words, such as jvm17, unsearchable.
Sites built without the Lunr extension keep using DocSearch, so releasing this bundle doesn't change the live site until datastax-docs-site's playbooks point at it.