-
Notifications
You must be signed in to change notification settings - Fork 841
Description
Current behavior
The Algolia DocSearch integration in the docs site has several issues:
- Duplicate search results: The DocSearch crawler indexes breadcrumb navigation, heading-level anchors, and same-titled pages from different sections, producing duplicate or near-duplicate results.
- Search bar spans full viewport width: When the search modal opens, the search input bar stretches across the entire screen instead of staying within the modal. This is caused by docfx's default CSS rule
header { position: fixed; top: 0; left: 0; }unintentionally applying to DocSearch's<header class="DocSearch-SearchBar">element. - Search not visible in local builds: The custom TOC template (
toc.html.tmpl) that renders the DocSearch button is silently ignored by newer docfx versions, which expecttoc.html.primary.tmpl.
Expected behavior
- Search results should be unique and deduplicated
- The search bar should stay within the modal bounds (~560px)
- Search should be visible and functional in local doc builds
How to reproduce
- Visit the docs site and open DocSearch (Cmd+K)
- Search for "MVUX" or any common term
- Observe duplicate results and the search input spanning the full viewport width
Workaround
None
Works on
All platforms (browser-based docs site)
Issues found and fixed
-
Breadcrumb duplicates — The crawler indexed
<div id="breadcrumb">content as separate search records with#breadcrumbanchors. Fixed by filtering those intransformItemsand addingdata-docsearch-excludeto the breadcrumb template. -
Same-page heading duplicates — DocSearch creates one record per heading level, so a single page could appear multiple times. Fixed with URL-based deduplication that keeps only the first hit per base page URL.
-
Same-titled different pages — Pages like workshop variants shared identical titles, making results look like duplicates. Fixed by detecting same-titled groups and appending a distinguishing URL path segment to the display text (updating both
_snippetResultand_highlightResultso DocSearch actually renders it). -
Navigation noise in index — The crawler was indexing navbar, footer, and sidebar content. Fixed by adding
data-docsearch-excludeto those elements via new template overrides (affix.tmpl.partial,footer.tmpl.partial,breadcrumb.tmpl.partial, and_navbar.tmpl.partial). -
Search bar spanning full viewport width — docfx's default CSS
header { position: fixed; top: 0; left: 0; }was applied to DocSearch's<header class="DocSearch-SearchBar">, pulling it out of the 560px modal. Fixed with a CSS override inmain.css. -
Search not visible in local builds — The custom TOC template was named
toc.html.tmplbut docfx 2.73+ expectstoc.html.primary.tmpl, so the#docsearchcontainer was silently missing. Fixed by renaming the file and pinning the docfx version.