Goal: Doc Search Ranking

Project-scoped roadmap/ pages account for the majority of the documentation site’s content and therefore dominate its search results. A reader searching for how the system works today is served design drafts, session logs, and plans from projects that may never have shipped. This project explores and implements a ranking adjustment so that durable sections surface first, without hiding roadmap content from readers who want it.

Context

The site’s search is Pagefind, run by Starlight at the end of the production build. Every page contributes equally to the index today — there is no per-section weighting.

The imbalance is structural, not incidental: 683 of 1160 source content files (59%) live under roadmap/, which the production build renders as 689 of 1169 indexed pages. Roadmap pages are also long and prose-heavy, which suits Pagefind’s default ranking.

The same concern has already been addressed for agent-facing surfaces: astro.config.mjs excludes roadmap/** from /llms.txt and the llms-full.txt bundles, on the grounds that roadmap pages are project-internal and decay in relevance after a project ships. Human search has no equivalent treatment. This project decides what the human-facing equivalent should be.

Scope

In scope:

• Ranking or filtering of roadmap/ pages in the deployed site’s search.
• The build-time mechanism that applies it, and where the path rule lives.
• A regression test that fails if the ranking adjustment stops taking effect.

Out of scope:

• Changing what content lives under roadmap/, or archiving completed projects.
• The search UI’s appearance or interaction model.
• The starlight-llms-txt agent surfaces, which already exclude roadmap/**.

Constraints

• Starlight’s pagefind configuration option cannot express this. It exposes only site-global ranking weights (pageLength, termFrequency, termSaturation, termSimilarity) plus indexWeight and mergeFilter, and the latter two apply only to merged multisite indexes. Any per-path behavior must come from the indexed HTML.
• The adjustment must survive both deploy targets. The preview build uses the /documentation/ base path and production uses /; any path matching keys off the built file path, not the URL.
• Starlight internals should not be vendored. Overriding Page.astro — the component that carries data-pagefind-body — is possible but couples the site to a component Starlight discourages overriding.

Repositories

Repository	Role	Planned Changes
documentation	Doc site	Build-time mechanism, configuration, project documentation, and a regression test

Success Criteria

1. For a term that appears in both a durable page and a roadmap page, the durable page ranks above the roadmap page in the deployed site’s search.
2. Roadmap pages remain reachable through search — demotion, not exclusion — unless the project explicitly decides otherwise.
3. The path rule that classifies a page as roadmap lives in exactly one place, and reads clearly next to the existing starlight-llms-txt exclude rule.
4. A test fails if the adjustment stops applying, so a Starlight or Pagefind upgrade cannot silently revert it.
5. make pr-checks passes.