Docs search is silently scoped to one section, so pages that exist return zero or wrong results

[tux234]

Fleet versions

• Discovered: fleetdm.com, 2026-09-02
• Reproduced: fleetdm.com, 2026-09-02

Web browser and operating system: Any (reproduced directly against the Algolia index)

---

💥 Actual behavior

Docs search is hard-scoped to the section of the page you happen to be on, with no indication that it is scoped and no way to widen it. Searching for a page you know exists returns zero results, or a list of confident-looking wrong results, depending on which page you started from.

Each docs page passes a fixed facet filter to DocSearch, in website/assets/js/components/docs-nav-and-search.component.js:83:

filterForSearch = {
  'facetFilters': [`section:${this.searchFilter}`]
};

Seven different scopes are hard-coded across the docs pages (docs, controls, software, queries, policies, vitals, tables), and the rendered search box is a plain input with the placeholder "Search". Nothing tells the reader which slice they are searching.

Reproduction against the index (the public search-only key is committed in website/config/custom.js for this purpose):

q() { curl -s -X POST "https://NZXAYZXDGH-dsn.algolia.net/1/indexes/fleetdm/query" \
  -H "X-Algolia-API-Key: f3c02b646222734376a5e94408d6fead" \
  -H "X-Algolia-Application-Id: NZXAYZXDGH" \
  -d "{\"query\":\"$1\",\"facetFilters\":[\"section:$2\"],\"hitsPerPage\":3}" \
  | jq -r '"hits=\(.nbHits)  top=\(.hits[0].url // "ZERO RESULTS")"'; }

From the /docs search box (section:docs):

Query	Result from /docs	Where the page actually is
compensation	0 hits	/handbook/company/communications#compensation
hiring	1 hit, unrelated patch-management guide	/handbook/company/leadership#hiring
CEO flaws	12 hits, top is deploy-fleet-on-ubuntu-with-elastic	/handbook/company/leadership#ceo-flaws
levels of confidentiality	35 hits, top is build-configuration-profiles-with-ai	/handbook/company/communications#levels-of-confidentiality

From a narrower box, for example /vitals (section:vitals):

Query	Result from /vitals
gitops	0 hits
rest api	0 hits
disk encryption	5 hits, vitals-only

All of that content is indexed and reachable with a different facet, so this is a scoping and discoverability problem rather than a coverage gap. section:handbook returns the correct page as the top hit for every query in the first table.

The two failure shapes are both bad, and the second is worse:

1. Zero results. A reader on /vitals who searches "gitops" is told, in effect, that Fleet has no GitOps documentation.
2. Confidently wrong results. "levels of confidentiality" returns 35 hits from the docs slice. Nothing signals that the actual page was excluded by a filter the reader never set.

🛠️ Expected behavior

Searching from any docs page can reach Fleet's documentation, guides, and handbook. Concretely, any one of:

• Drop the hard facet filter and rank by relevance across the index, optionally boosting the current section.
• Keep the section scope but show it in the UI and let the reader clear it, for example a "Searching docs. Search all of fleetdm.com instead" affordance.
• At minimum, when a scoped search returns zero or few results, fall back to an unscoped query and label those results as coming from elsewhere.

🧑‍💻 Steps to reproduce

These steps:

• Have been confirmed to consistently lead to reproduction in multiple Fleet instances.
• Describe the workflow that led to the error, but have not yet been reproduced in multiple Fleet instances.

1. Go to https://fleetdm.com/docs (any docs page).
2. Search for compensation in the docs search box.
3. Zero results, though https://fleetdm.com/handbook/company/communications#compensation exists.
4. Go to https://fleetdm.com/vitals and search gitops. Zero results.
5. Back on /docs, search levels of confidentiality. Many results, none of them the page of that name.

🕯️ More info (optional)

A few things ruled out while narrowing this down, to save the next person the work:

• Not a coverage gap. I probed 40 live docs and article pages (verified HTTP 200) by searching each page's own exact title. With the correct per-section facet applied, every one was findable. The index is populated.
• Not guides being excluded from docs. Guides are indexed twice, once as section: ['guides','articles'] and again as section: ['docs','all-docs'], so /docs search does surface guide pages. Only cross-section content, most visibly the handbook, is unreachable.
• Release notes are not crowding the docs box. They dominate an unscoped query, but section:docs excludes them. Relevance inside a single section looks reasonable: disk encryption, scim, software install script, and host vitals each put an on-target page in the top three.

Two smaller things noticed in passing, both separable from the fix above:

• The section taxonomy overlaps heavily. Facet counts total roughly 44,000 records over 2,681 distinct pages: all-docs 13,663, articles 9,733, docs 5,709, tables 4,310, guides 4,151, software 2,806, handbook 2,531, then queries/reports 384 each, controls 270, policies 96, vitals 88. Pages belong to several sections at once, and docs versus all-docs versus guides is not self-evident.
• One page can consume most of a result page. A section:docs query for disk encryption returns 23 records covering only 10 distinct pages, since each heading anchor is its own record.

[tux234]

Related coverage defect found while auditing this: case study pages are live but absent from the index entirely, so search cannot return them regardless of scope. Filed separately as #52386, since that one is a crawler/coverage problem while this one is content that is indexed but filtered out.

Also worth recording here: index freshness is not a factor. I probed 94 live pages added in the last 120 days by searching each page's own title, and the only misses were those case studies. The newest page confirmed present in the index was published 2026-09-01, the day before this was filed.

[eashaw]

Closing this issue, we changed the search bar on the website to take users to a google search that is scoped to the Fleet website.

[fleet-release]

Readers search in fog
one section blocks their passage
open all the doors