At the beginning of every year I spend some time updating my website. I can’t help it. It’s become some sort of ritual. Last year I moved away from my custom Gulp-based monstrosity to Astro as a static site generator. This year, in addition to a slight redesign, I wanted to make the site searchable.
My new year resolutions include blogging more and releasing a new Unreal Engine plugin (wish me luck!). This means adding many new pages to my website, which is now made of ~500 assets including pages, images, etc. — twice as many as last January! Being able to search for specific content might become useful.
Since the time I can dedicate to my website is limited — and my web dev skills aren’t as sharp as they used to be — I needed a solution that would mostly work out-of-the-box.
- It promises almost zero config. Pagefind runs after the site has been built and indexes the files in the built output folder automatically.
- It provides a fully-functional search UI by default.
- It’s the same solution used by Starlight — Astro’s docs — so I had an example to look at.
- It’s all JS and self-hosted. I don’t want to integrate remote APIs if I can avoid it.
Pagefind can be installed from npm:
Creating the search page
The following is my Astro search page. The code is more or less a copy-paste of the code available in the Pagefind docs.
Following the same approach used by Astro in their docs, I’ve created a custom Astro integration that’s responsible for running Pagefind at the end of the build.
In my case I went with the programmatic approach because I wanted to index only specific parts of the website (namely posts and tools) and doing so programmatically seemed easier — not sure if it ultimately was though. 😄
In both cases, after running
npx astro build, a new
pagefind folder will be created in the built output folder, containing all the required files.
And that’s all it takes to get a working search input field and display the search results. Running
npx astro preview allows to preview things:
Improving indexed data
While Pagefind does a nice job by default at indexing content, I found that spending some time configuring what content is indexed can drastically improve the search results.
For my website I’ve marked the main content with the
data-pagefind-body tag and ignored some items (like breadcrumbs) by tagging them with
In some instances, I wanted to display a different title in the search results than the one specified in the
<title> tag, which can be achieved with the
I’m really happy about how website search turned out — especially considering the low effort required to get it working! I only have two minor complaints:
- Search can’t be testing during development — or at least I wasn’t able to find a way to do so. Having to build and preview slows things down a bit (although it’s still really fast compared to, say, compile any Unreal Engine project).
- I wasn’t able to find a way to let Astro bundle the Pagefind CSS and JS files. In my case that’s probably even better since the search box exists in its own separate page, but it might have been useful if the search box was visible in every page.