docs: make site search usable (scope to reader's language, stop one page filling results) - #15745
Open
devGregA wants to merge 3 commits into
Open
docs: make site search usable (scope to reader's language, stop one page filling results)#15745devGregA wants to merge 3 commits into
devGregA wants to merge 3 commits into
Conversation
Every record in the DocSearch index already carries a lang facet and every built page already emits <html lang>, but the search box never filtered on it, so one query searched all languages at once. The effect is worst on common terms. Searching "jira" returned the same page in Japanese, French, Spanish, German and English as the top five results, so five of the first six slots were copies of one page in languages the reader cannot read. Adding a language filter at query time gives the reader results in the language they are already browsing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
DocSearch groups results by section rather than by page, so a single long page could occupy every slot. Searching "reimport" returned five results that were all subsections of the Reimport page, so the reader saw one page's table of contents instead of the five best pages. Cap the hits from any one page at two, which keeps the useful "page plus best matching section" pair and frees the remaining slots for other pages. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
devGregA
changed the title
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
1 participant
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.
Docs search returns results that are hard to use. Two of the causes are in this repo and are fixed here. The rest are in the Algolia crawler configuration and are written up at the bottom for whoever holds that access.
Fix 1: search every language at once
Querying
jiraagainst the live index returned, as the top five results:Five of the first six slots were the same page in five languages. Nothing needs to change on the Algolia side, because the index already tags every record with a
langfacet:Every built page already emits the right
<html lang>. The only missing piece was passing a facet filter at query time. The filter falls back toenif a page somehow renders without a lang attribute, so it degrades to today's English behaviour rather than returning nothing.Fix 2: one page filling every slot
This one predates the translations. DocSearch groups results by section, not by page, so a single long page can occupy the whole result list. Searching
reimportreturned:Five results, one page. The reader gets that page's table of contents instead of the five most relevant pages. This caps hits from any one page at two, which keeps the useful "page plus best matching section" pair and frees the rest of the list.
Still broken, needs crawler access
These cannot be fixed from this repo. The crawler config is not in version control and there is nothing in
.github/that touches Algolia, so it lives in the Algolia crawler UI. The index was last refreshed 2026-08-18, so the crawler itself is running fine.h3headings are not indexed at all. The English docs use###926 times, and the index contains nolvl3records whatsoever (onlylvl1,lvl2,lvl4andcontent). Heading IDs are generated correctly on our side (autoHeadingID = true, and built pages carry<h3 id=...>), so this is a selector problem in the crawler. Close to a thousand subsections are currently invisible as search targets, andlvl4sections are being indexed while theirlvl3parents are skipped.Overview pages do not rank for their own topic. Searching
import a scanreturns Smart Upload, Universal Parser twice and Universal Importer twice, and never returns the import introduction. Someone searching the most obvious phrase gets the most advanced answers. This wants a ranking signal that favours introductory pages.Many records anchor to
#main-contentrather than the heading that actually matched, so clicking a result lands the reader at the top of a long page.Duplicated hierarchy labels, for example
Deduplication > Location Drift Matching (Pro) (Pro)andDeduplication Tuning (Open Source) (Open Source), which looks like the page title and a crawler level both contributing the edition suffix.Every concept is documented twice, once for Open Source and once for Pro, and search returns both, so half the results are for the edition the reader is not running. The index already carries an
audiencefacet (pro,opensource,public) that nothing currently uses. Filtering on it is possible from this repo, but it needs a product decision about the default, so it is deliberately not in this PR.Verifying after deploy
Search from an English page and from a
/fr/page and confirm each stays in its own language, then searchreimportand confirm the results are several different pages rather than one page repeated.🤖 Generated with Claude Code