How Search Works | Compass Docs

Understand how Compass uses Pagefind to generate scalable static search for your docs.

Compass uses Pagefind for static full-text search. The search index is generated from the built HTML after Astro finishes its build, so Compass does not inline a giant search payload into every page.

The main files

src/components/SearchHero.astro for the homepage search UI
src/components/Sidebar.astro for the sidebar search UI
src/scripts/docs-search.ts for the shared Pagefind client logic
package.json for the build step that runs pagefind --site dist

Why Compass uses Pagefind

Pagefind is a better fit for a growing docs site than shipping a full search index in page HTML.

It helps because:

search indexing happens at build time
the browser loads small search chunks on demand
result previews can come directly from each article’s frontmatter description
the same search system can power both the hero search and sidebar search

What gets indexed

Compass marks canonical article pages with data-pagefind-body, which tells Pagefind which HTML should become searchable.

This keeps search focused on docs content rather than indexing:

duplicate route aliases
repeated sidebar navigation text
homepage marketing copy

Compass also attaches article metadata for the category label. For active queries, the custom search UI prefers Pagefind’s matched excerpt so readers can see highlighted hit context, then falls back to each article’s frontmatter description when no excerpt is available.

If an article should not appear in search, set:

hideFromSearch: true

Compass will omit that page from the indexed article set and keep it out of suggested search prompts.

Local search workflow

Because Pagefind runs after the site build, the full search experience is available after:

npm run build
npm run preview

During npm run dev, the site UI still works, but the generated Pagefind bundle does not exist yet.

When to customize search

change src/scripts/docs-search.ts when you want to change result rendering or highlight behavior
change the search components when you want different layouts or messages
change the article templates when you want to adjust what Pagefind indexes