Fix docs search ranking and index staleness - #280
Merged
Conversation
Two unrelated-looking problems with the same root: search results were ranked almost entirely by heading depth, and the index lagged releases. Rank guides above generated API reference ----------------------------------------- The Algolia index ranks on desc(weight.pageRank) first, but the crawler never set pageRank, so all 16.5k records sat at 0 and the criterion was inert. API reference is ~70% of the index, so it buried hand-written guides on common queries. The crawler config now assigns pageRank as "version band + section weight" (latest release > older > unreleased; tutorials > how-to > explanation > api). That alone was not enough: the index sets exactOnSingleWordQuery to "attribute", so for a one-word query only a hit matching the *whole* attribute counts as exact. A generated heading that is literally "token" qualified; the "Security & Token Model" page did not. Algolia resolves `exact` before `custom`, so pageRank never got a say. Setting it to "word" at query time lets pageRank decide. It is set here rather than in the index settings because free DocSearch grants no editSettings key. Verified against the live index — searching "token" now returns the security concepts page, "agent" the agents tutorial, "peer" the list-other-peers guide. Exact API symbol lookup is unaffected. Reindex on release ------------------ Docusaurus contextual search filters on the current version's docusaurus_tag. A new version therefore has zero records until the crawler runs, and the search box returns nothing at all. 0.29.0 shipped on 23 Jul against a monthly crawl last run on 17 Jul, so docs search was dead for four days. The crawler is now on a weekly schedule, and this adds a job that triggers a reindex when versions.json changes. Requires ALGOLIA_CRAWLER_USER_ID and ALGOLIA_CRAWLER_API_KEY secrets.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR aims to improve Docusaurus/Algolia DocSearch behavior by (1) adjusting query-time ranking so guide/concept pages aren’t buried by API reference headings on single-word searches, and (2) preventing “empty search results after a docs version release” by triggering an Algolia crawler reindex when a new docs version is published.
Changes:
- Add an Algolia
exactOnSingleWordQuery: "word"search parameter to improve single-word query ranking behavior. - Add a post-deploy GitHub Actions job to trigger an Algolia crawler reindex when
versions.jsonchanges (docs release).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
docusaurus.config.ts |
Tunes DocSearch query parameters to improve ranking for single-word searches. |
.github/workflows/docs.yaml |
Adds a post-deploy reindex job intended to prevent contextual-search “no results” after docs version releases. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Diffing HEAD^..HEAD only inspects the tip commit, so a push carrying several commits missed a release whose versions.json change was not last — reproduced against real history. Diff the full pushed range via github.event.before instead, falling back to the tip when it is absent (workflow_dispatch) or unresolvable (first push to a branch). This needs full history, since `before` can point anywhere. Also drop the reindex job to contents:read. It inherited pages:write and id-token:write from the workflow, which it never uses.
Gating the job on push events guarantees github.event.before exists, which removes the fallback branch, the cat-file probe and the env var. Folding the check into the curl step as an early exit removes the GITHUB_OUTPUT plumbing and the second step's condition.
Unanchored, the dot is a regex wildcard, so versionsXjson would also match. No such path exists, but -F makes the exact-path check explicit.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (1)
.github/workflows/docs.yaml:81
- The
git diffcheck can silently skip reindexing whengithub.event.beforeisn’t available locally (e.g., force-push where the prior commit is no longer reachable from fetched refs). With the defaultbash -eo pipefail, the pipeline exits non‑zero and the|| exit 0makes this look like “no versions.json change”, leaving the index stale. Consider capturing the diff output and falling back to triggering a reindex when the diff can’t be computed.
run: |
git diff --name-only ${{ github.event.before }} ${{ github.sha }} \
| grep -qxF versions.json || exit 0
curl -sS -f -X POST \
-u "${{ secrets.ALGOLIA_CRAWLER_USER_ID }}:${{ secrets.ALGOLIA_CRAWLER_API_KEY }}" \
"https://crawler.algolia.com/api/1/crawlers/9bc2ab68-0ce9-4f44-9824-3a48219680b2/reindex"
czerwiukk
approved these changes
Jul 27, 2026
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.
Fixes FCE-3620