docs: fix search ranking, add relevance smoke test and heading discoverability

[kaviththiranga]

Problem

Searching the docs returned everything except the page you wanted. "Authorization" ranked the authorization overview at #57, and the top 20 results were just 5 pages — 4 of them AuthzRole CRD references.

Two causes in the Algolia index config:

1. searchableAttributes searched hierarchy.lvl0 (the sidebar category label) ahead of lvl1 (the page's H1). The API-reference category is labelled exactly Authorization, so its CRD pages beat the guide titled "Authorization in OpenChoreo".
2. attributeForDistinct was url, which includes the anchor — so one page contributed a record per heading and could fill every slot.

Fixed in the Algolia dashboard (not in this PR)

hierarchy.lvl0 moved after lvl6; attributeForDistinct → url_without_anchor with distinct: 2; both mirrored into the crawler's initialIndexSettings so a reindex can't revert them; /docs/category/* stubs no longer indexed.

Query	before	after	distinct pages in top 20
authorization	#57	#1	3 → 20
rbac	#21	#3	1 → 20
observability	#4	#5	4 → 20
custom roles / cel conditions	#1	#1	4 → 13 / 12 → 14

In this PR

• scripts/search-smoke.mjs — replays the site's real search query and asserts the expected page ranks and that results span ≥8 distinct pages. No dependencies. Daily workflow + npm run test:search.
• scripts/ALGOLIA.md, algolia-index-settings.json — the Algolia config only lived in a dashboard with no change history. Now reviewable and restorable.
• Heading changes — search ranks headings far above body prose, so a term only in prose is nearly unfindable. This was reported for OpenTelemetry: the OTLP collector endpoints are documented, but no heading said "OpenTelemetry", "OTLP" or "collector". An audit of all 147 live docs files found 27 such terms; the top ones are fixed:

### Traces (OpenTelemetry) {#traces}
#### Instrumenting Applications with the OpenTelemetry Collector (OTLP) {#instrumenting-applications}
## Authenticated mirrors (imagePullSecrets) {#authenticated-mirrors}
## Configuring a ClusterSecretStore (Vault, AWS, GCP, Azure) {#configuring-a-clustersecretstore}
### GitOps installations (Flux, Argo CD) {#gitops-installations}

Anchors are pinned to their original IDs, so existing links keep working. Applied to both docs/ and versioned_docs/version-v1.2.x/ — the live /docs/* pages come from the versioned copy.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 2f34b8d2-0439-4148-b016-27ab3b5f5e33

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}