feat(algolia): add facets based on version for search

[haarchri]

When browsing older documentation versions (for example, v1.20), search results currently all content from latest....
This leads to confusion when users discover features or APIs in search results that don’t actually exist in the version they’re viewing.

This PR introduces version-aware search filtering using Algolia facet filters. https://www.algolia.com/doc/guides/managing-results/refine-results/faceting
Search results will be restricted to the documentation version the user is currently viewing.

• Added logic to detect the current page version via .Page.Params.version.
• Configured DocSearch to apply a facetFilters value dynamically:

['docsearch:version:X.XX']

• Added special handling for the master version - uses docsearch:version:0.0.0-master, which matches the existing meta tag convention where master is labeled 0.0.0-master to keep it de-ranked in search

Background

Each page already includes:

which the Algolia crawler indexes.

curl https://docs.crossplane.io/v2.0/composition/  | grep -A 10 "docsearch"
<meta name=docsearch:modified content='August 14, 2025'><meta name=docsearch:version content="2.0">

curl https://docs.crossplane.io/v1.20/concepts/  | grep -A 10 "docsearch"
<meta name=docsearch:modified content='May 21, 2025'><meta name=docsearch:version content="1.20">

Required: Algolia configuration

After this PR is merged, someone with Algolia admin access must enable faceting:

• Open Algolia Dashboard

• Go to the crossplane index

• Navigate to Configuration → Facets

• Add:
  filterOnly(docsearch:version)
  to Attributes for faceting

• Save

Important: The docsearch:version attribute is already indexed, so no re-crawl is required.

Testing:

curl http://localhost:1313/v2.1/composition/ | grep -A 10 "docsearch"
...
<script>
    docsearch({
    container: '#docSearch',
    appId: 'xxx',
    indexName: 'crossplane',
    apiKey: 'xxxxx',
    placeholder: 'Search the docs',
    searchParameters: {
      facetFilters: ['docsearch:version:2.1']
    }
    });
</script>

To verify this PR:

• Open any versioned docs page (for example, /v1.20/concepts/providers/)
• Open DevTools → Network
• Perform a search
• Inspect the request to algolia.net

{"requests":[{"query":"t","indexName":"crossplane","attributesToRetrieve":["hierarchy.lvl0","hierarchy.lvl1","hierarchy.lvl2","hierarchy.lvl3","hierarchy.lvl4","hierarchy.lvl5","hierarchy.lvl6","content","type","url"],"attributesToSnippet":["hierarchy.lvl1:10","hierarchy.lvl2:10","hierarchy.lvl3:10","hierarchy.lvl4:10","hierarchy.lvl5:10","hierarchy.lvl6:10","content:10"],"snippetEllipsisText":"…","highlightPreTag":"<mark>","highlightPostTag":"</mark>","hitsPerPage":20,"clickAnalytics":false,"facetFilters":["docsearch:version:2.0"]}]}

we see the facetFilters

Fixes: #1008

[netlify]

✅ Deploy Preview for crossplane ready!

Name	Link
🔨 Latest commit	7ddc4bf
🔍 Latest deploy log	https://app.netlify.com/projects/crossplane/deploys/697a2e9f3b966800084f9c6c
😎 Deploy Preview	https://deploy-preview-1051--crossplane.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 93 (🔴 down 3 from production) Accessibility: 90 (🔴 down 2 from production) Best Practices: 92 (no change from production) SEO: 100 (no change from production) PWA: 70 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[haarchri]

This is required because partialCached would cache the first version rendered and reuse it across pages, causing the wrong version filter to be applied.

[jbw976]

This is very interesting @haarchri! Hopefully everything works smoothly after this PR gets merged 😂

One immediate question for you - do you know what the UX is going to be for showing multiple versions in the search? will the search popup make it clear which version each result is from? Will it favor newer versions over older versions? are you able to see this in your local testing, or do we have to merge this, update Algolia config, and see what happens?

[jbw976]

RE: the Algolia config instructions

Add:
filterOnly(docsearch:version)
to Attributes for faceting

Looks like we have a version attribute for faceting already on https://dashboard.algolia.com/apps/9UXKYX61NK/explorer/configuration/crossplane/facets, is that useful?

I was able to do a network inspect on the preview site and when searching it does look like facetFilters are being sent in the request, so that's a good sign 😉

facetFilters=%5B%22docsearch%3Aversion%3A0.0.0-master%22%5D

[jbw976]

why 0.0.0-master instead of just master? does it need the numbers to work correctly?

[jbw976]

ah, that's how we're setting it in the header: https://github.com/crossplane/docs/blob/master/themes/geekboot/layouts/partials/header.html#L11-L12