In my astro starlight repo, i made a pages directory and used file based routing just like i would in a normal astro repo. So I have my documentation generated by .md files, and some pages handled by astro's router. But I want to use the search function, like the ability to search through documentation from one of the custom pages I made. How can I do it ?
#Astro Starlight: how to use pagefind/cmd k search in pages ?
muted pulsar
river oarBOT
Hi @muted pulsar. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Starlight’s built‑in search (Pagefind / Cmd+K) is only documented as part of the Starlight layout and header, not as a standalone API you can call from arbitrary Astro pages. The knowledge sources don’t describe a way to programmatically trigger the default search modal from a custom src/pages/*.astro route.
What is documented:
- Search is enabled automatically and appears in the header via the
Searchoverride component, which loads Pagefind’s UI and modal. [Header overrides; Site search] - If you disable Pagefind (
pagefind: falsein config), the default search UI disappears, but you can override theSearchcomponent to render your own search UI (e.g. for another provider). This customSearchis always rendered when you use the Starlight header. [Header overrides; pagefind config]
For custom pages, Starlight suggests reusing its layout via <StarlightPage> so that the standard header (and thus the search button / Cmd+K behavior) is present on those routes: [Pages guide]
---
// src/pages/custom-page/example.astro
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
---
<StarlightPage frontmatter={{ title: 'My custom page' }}>
<p>This is a custom page that still uses the Starlight layout and header.</p>
</StarlightPage>
With this approach:
- Your custom page uses the same header as the docs pages.
- The search button and Cmd+K shortcut work there the same way they do on documentation pages.