The search feature provides full-text site search powered by Pagefind. It includes a search dialog triggered from the nav bar or via keyboard shortcut, and automatic search index building as a post-build step.
How it works#
- After each production build, the theme runs Pagefind to index all built HTML pages.
- The nav bar includes a search button (magnifying glass icon).
- Clicking the button or pressing Cmd+K (Ctrl+K on Windows/Linux) opens a search dialog.
- Results are fetched from the Pagefind index and displayed with highlighted matches.
Enabling search#
Search is enabled by default. The theme integration builds the Pagefind index, and the nav bar shows the search button automatically.
You need pagefind installed as a dev dependency in your project:
pnpm add -D pagefind
To disable search, pass search: false to the theme integration, which skips
the index build (and the check that pagefind is installed):
// astro.config.ts
universityTheme({ search: false });
The nav’s search button is controlled separately: pass search={false} to
BaseLayout or Nav to hide it, on its own or alongside the integration
option.
<BaseLayout title="My Page" search={false}> ... </BaseLayout>
Nav props#
The Nav component accepts a search prop:
| Prop | Type | Default | Description |
|---|---|---|---|
name * | string | --- | Site name — rendered as a text wordmark when no logo is provided, and used as alt text for the logo when one is. |
links | NavLink[] | [] | Navigation links displayed in the top bar. |
search | boolean | true | Whether to show the search button and dialog. |
logo | ImageMetadata | --- | Logo image (light mode). When omitted, the site name renders as a text wordmark instead. |
logoDark | ImageMetadata | --- | Logo image (dark mode). Only used when `logo` is also provided. |
logoCompact | ImageMetadata | --- | Compact logo (e.g. a crest or monogram) swapped in below the mobile breakpoint, where a wide horizontal lockup would wrap the nav bar. Only used when `logo` is also provided; when omitted the full logo is shown at every width. |
logoCompactDark | ImageMetadata | --- | Compact logo (dark mode). Only used when `logoCompact` is provided. |
homeHref | string | --- | Where the logo links (default the site base). |
labels | Partial<ThemeLabels> | --- | Translations of the nav's labels; any left out stay English. |
Keyboard shortcuts#
- Cmd+K / Ctrl+K — open or close the search dialog
- Escape — close the dialog
- Arrow Down / Arrow Up — navigate results
- Enter — follow the selected result
Development vs production#
Search only works against a built site. During development (pnpm dev), the
search dialog will open but no results will be available because the Pagefind
index doesn’t exist yet.
To test search locally, build and then preview:
pnpm build
pnpm preview
Notes#
- The search index is built automatically in the
astro:build:donehook. If search is enabled butpagefindisn’t installed in the project, the build fails with an error telling you to add it or passsearch: false; a failed Pagefind run also fails the build. - If the index can’t be loaded at runtime — in the dev server, or on a build
made with
search: false— the site still works and the search dialog shows a “Search index not available” message. - Pagefind indexes all rendered HTML pages by default. Use
data-pagefind-ignoreon elements you want to exclude from search results.