Add high-performance search to static sites with PageFind
Pagefind is a fantastic addition to static site search tools. With very little configuration, it quickly indexes a static build and gives you instant-updating, filterable search. Use the default UI on a search page or, as on this site, build it into a modal. It’s small (as of this writing, just over 2KB minified and gzipped). It has many configuration options, and the maintainer is responsive and open to new ideas. And it has a nice dev mode, running on
I first used Pagefind in Starlight. Check out Comparing docs site builders: VuePress vs Starlight
Here’s everything needed to get going.
The examples here use
npm run and
yarn should work, but I have not tested them.
and add the Pagefind CSS and JS to your site.
Add scripts to
package.json. Many ways to factor these. I do as below, where
build:site is the framework’s build script. Note that Pagefind indexes a local build, so you’ll need to generate one first, and when changing the site source you may need to stop and rerun the dev script. (Replace the ALL CAPS text with your real content.)
Pagefind works well out of the box. If search hits aren’t showing the correct heading, summary, or image, fine tune things with
data-pagefind-meta="heading"to manually specify the heading. Here I assume the heading is visible on the indexed page, but it doesn’t have to be — see the Pagefind docs for alternative approaches.
data-pagefind-meta="image[some-attribute], image_alt[some-other-attribute]"to manually specify the image used by search hits. Here I assume the image you want to show in in the search UI is visible on the indexed page, but it doesn’t have to be — see the Pagefind docs for alternative approaches.
data-pagefind-bodyto manually set a container for Pagefind to index inside of. (Pagefind will still respect
data-pagefind-*attributes outside of this container.) Use
data-pagefind-ignoreto specify content Pagefind should not index.
Putting those together, you might get a page structure similar to this. The highlighted lines are indexed.
If your markup has a
data-pagefind-filter attribute, the default Pagefind adds a filter pane to the default search UI, with filters grouped into collapsible groups.
With the following markup, Pagefind’s default search UI will have a filter pane with two collapsible filter groups, “Author” and “Tags”.
Filters do not have to be visible on the page. One way of indexing filters which do not show on the indexed page’s front end is to use the
Another is to use
See the Pagefind docs for more.
You can see Pagefind in action on this site by clicking “search” in the desktop sidebar or mobile header.