How Search Works

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/components/SearchPreviews.astro for the shared frontmatter preview payload
• 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 from one shared page-level lookup built 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.

Articles with status: 'draft' or status: 'archived' are treated as non-public. Compass does not generate their article routes, include them in navigation or redirect aliases, or pass them to Pagefind. published and deprecated articles remain public unless you opt them out of search.

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.

The search dropdown is keyboard-friendly: use / or Control/Command + K to focus search, ArrowDown and ArrowUp to choose a result, Enter to open it, and Escape to close the dropdown. Compass gives each search input a stable ID and connects it to its result list with ARIA state so assistive technology can track when results are available and which keyboard-highlighted result is active.

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 src/components/SearchPreviews.astro if you need to alter how fallback previews are delivered to the browser
• change the article templates when you want to adjust what Pagefind indexes