Skip to content

fix: Algolia DocSearch results are duplicated and search bar spans full viewport width #22788

@Jen-Uno

Description

@Jen-Uno

Current behavior

The Algolia DocSearch integration in the docs site has several issues:

  1. 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.
  2. 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.
  3. 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 expect toc.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

  1. Visit the docs site and open DocSearch (Cmd+K)
  2. Search for "MVUX" or any common term
  3. 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

  1. Breadcrumb duplicates — The crawler indexed <div id="breadcrumb"> content as separate search records with #breadcrumb anchors. Fixed by filtering those in transformItems and adding data-docsearch-exclude to the breadcrumb template.

  2. 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.

  3. 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 _snippetResult and _highlightResult so DocSearch actually renders it).

  4. Navigation noise in index — The crawler was indexing navbar, footer, and sidebar content. Fixed by adding data-docsearch-exclude to those elements via new template overrides (affix.tmpl.partial, footer.tmpl.partial, breadcrumb.tmpl.partial, and _navbar.tmpl.partial).

  5. 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 in main.css.

  6. Search not visible in local builds — The custom TOC template was named toc.html.tmpl but docfx 2.73+ expects toc.html.primary.tmpl, so the #docsearch container was silently missing. Fixed by renaming the file and pinning the docfx version.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions