Search operations

How the index is built

Astro Starlight runs Pagefind after astro build. The index lands in dist/pagefind/ and is served as static files. The search modal downloads only the fragments it needs for a query.

Run the production build.
Confirm dist/pagefind/ exists and contains index fragments.
Preview the build and search for a term that appears on a known page.
Check that the result links to the correct canonical URL.

npm run build
ls dist/pagefind
npm run preview

Do not test search against the dev server. The index only exists after a production build.

Indexing controls

Pagefind indexes visible page content by default. Use attributes to exclude interface chrome and duplicated content:

<nav data-pagefind-ignore>...</nav>
<aside data-pagefind-ignore>Related links</aside>

For finer control, wrap the main content in data-pagefind-body on templates that include heavy navigation or sidebars. Exclude error pages, internal search pages and any route that should not appear in results.

Starlight already marks share controls and other chrome as ignored. Add attributes only where the default output includes noise.

Metadata and ranking

Pagefind uses the page title, headings and body text. Clear h2 and h3 structure improves recall. Frontmatter descriptions are useful for result summaries when the theme renders them into the page, but they are not a substitute for content.

Avoid keyword lists and duplicated text. They dilute relevance and make results harder to scan.

Zero-result handling

A search box that silently returns nothing feels broken. Provide a short empty state with:

The query that was searched.
Suggested broader terms or category links.
A contact path for missing content.
No automatic redirect to an unrelated page.

Review queries that return zero results. They usually reveal either missing content or vocabulary that does not match the docs.

Switching providers

Pagefind is the default because it needs no external service. Algolia DocSearch or a hosted search product can be added later, but it introduces credentials, indexing jobs and a third-party dependency. Disable Pagefind explicitly if another provider takes over.

For sitemap and metadata rules, see Sitemap and SEO.