Static Site Generators in Production

Adding Pagefind to an Astro Site

Starlight ships Pagefind already configured, but most Astro sites are not Starlight — marketing sites, blogs, product sites with a docs section. For those, Pagefind is a post-build step and a few attributes in your layouts. Done carelessly it indexes every sidebar and footer, ranks the changelog above the guide, and loads 40 KB of JavaScript on every page. Done carefully it gives near-hosted relevance at zero running cost with no impact on page metrics.

This guide adds Pagefind to a 1,400-page Astro 5 site in five steps and measures the result. The wider choice between search tools is covered in Search for Static Sites.

Prerequisites

  • An Astro 5 site with static output (output: 'static', the default).
  • Node.js 20 or later.
  • A shared layout component that wraps page content — Pagefind's attributes go there.
  • Twenty to sixty real search queries with the page each should find, for the relevance check at the end. Pull them from support tickets or existing analytics.

Step 1: Index After the Build

Pagefind reads HTML, so it runs after astro build:

// package.json
{
  "scripts": {
    "build": "astro build && pagefind --site dist",
    "preview": "astro preview"
  },
  "devDependencies": { "pagefind": "^1.3.0" }
}

On the 1,400-page site this added 4.9 seconds to a 38-second build. The output lands in dist/pagefind/: an entry script, the WebAssembly search engine, index chunks and page fragments. Everything is fingerprinted, so it can share the site's long-lived immutable cache rule from Cache Busting with Content-Hashed Filenames — except pagefind-entry.json and pagefind.js, which keep stable names and need a short cache lifetime so a new deploy's index is picked up.

Step 2: Draw the Content Boundary

Without guidance Pagefind indexes the whole <body>, including the header, navigation and footer on every page. A query for "pricing" then matches all 1,400 pages because "Pricing" is in the nav. Mark the content region in the layout:

---
// src/layouts/Doc.astro
const { title, section, weight = 1 } = Astro.props;
---
<main>
  <article data-pagefind-body data-pagefind-meta={`section:${section}`}>
    <h1 data-pagefind-weight="7">{title}</h1>
    <slot />
  </article>
  <aside class="toc" data-pagefind-ignore>...</aside>
</main>

Once any page carries data-pagefind-body, Pagefind indexes only regions with that attribute across the whole site, so pages without it — tag archives, the 404 page — drop out of search. That is usually what you want; add the attribute to any other layout whose pages should be findable.

What Pagefind indexes with and without a content boundary Two page wireframes. Without a boundary, the header, sidebar, article and footer are all indexed. With data-pagefind-body on the article, only the article is indexed, the heading is weighted seven times, and the table of contents is explicitly ignored. Index the answer, not the chrome No boundary header + nav (indexed) sidebar article footer (indexed) data-pagefind-body header + nav (skipped) skipped h1 · weight 7 article body (indexed) footer (skipped) One attribute in one layout removed 41% of indexed words on this site
The boundary is the single biggest relevance improvement: it removes words that appear on every page and therefore distinguish none.

Step 3: Weight and Filter

Two more attributes do most of the ranking work. data-pagefind-weight multiplies the importance of words inside an element; weighting the <h1> by 7 and <h2>s by 3 made a page whose title matched the query outrank a page that merely mentioned it. data-pagefind-filter indexes a facet the UI can filter on — section, product or version:

<article data-pagefind-body data-pagefind-filter={`section:${section}`}>

Changelog and release-note pages are the classic relevance problem: they mention every feature name, so they rank for everything. Give them data-pagefind-weight="0.3" on the body, or exclude them from the default filter so they appear only when the reader chooses "Changelog".

Step 4: Load the UI Only When Needed

Pagefind's default UI is convenient, but loading it in every page's <head> costs every visitor for a feature few use. Render the search trigger as plain HTML and import on first interaction:

---
// src/components/Search.astro
---
<button id="search-open" type="button" aria-haspopup="dialog">Search <kbd>/</kbd></button>
<dialog id="search-dialog" aria-label="Search the site"><div id="search"></div></dialog>
<script>
  const dialog = document.getElementById('search-dialog') as HTMLDialogElement;
  let loaded = false;
  async function open() {
    if (!loaded) {
      const link = Object.assign(document.createElement('link'),
        { rel: 'stylesheet', href: '/pagefind/pagefind-ui.css' });
      document.head.append(link);
      // @ts-ignore — served from dist/pagefind at runtime
      const { PagefindUI } = await import(/* @vite-ignore */ '/pagefind/pagefind-ui.js');
      new PagefindUI({ element: '#search', showSubResults: true, resetStyles: false });
      loaded = true;
    }
    dialog.showModal();
    dialog.querySelector('input')?.focus();
  }
  document.getElementById('search-open')!.addEventListener('click', open);
  addEventListener('keydown', (e) => {
    if (e.key === '/' && !(e.target as HTMLElement).closest('input,textarea')) { e.preventDefault(); open(); }
  });
</script>

The /* @vite-ignore */ comment stops Vite trying to bundle a file that only exists after the Pagefind step. showSubResults: true lets results link to the matching heading rather than the page top.

Eager versus lazy loading of the search UI Two page-load timelines. Eager loading fetches 38 kilobytes of search JavaScript and CSS during page load and adds 90 milliseconds of blocking time before first interaction. Lazy loading fetches nothing during page load; the same files load only when the reader opens search, taking about 120 milliseconds on first open. Who pays for search, and when Eager page load search UI 38 KB +90 ms TBT on every page Lazy page load search UI reader presses / ~120 ms, once Lighthouse 12 mobile; 6% of sessions on this site opened search at all
With 6% of sessions using search, eager loading charged the other 94% for nothing.

Step 5: Check Relevance in CI

Pagefind has a Node API that can build and query an index without a browser. Use it to run your query list against every build:

// scripts/search-check.mjs
import * as pagefind from 'pagefind';
import cases from './search-cases.json' with { type: 'json' };

const { index } = await pagefind.createIndex();
await index.addDirectory({ path: 'dist' });
const { search } = await (await import('../dist/pagefind/pagefind.js'));
let first = 0;
for (const { q, url } of cases) {
  const r = await search(q);
  const top = await r.results[0]?.data();
  if (top?.url === url) first++; else console.log(`miss: "${q}" → ${top?.url}`);
}
console.log(`${first}/${cases.length} ranked first`);
if (first < Number(process.env.SEARCH_BASELINE ?? 0) - 2) process.exit(1);

Store the baseline in the repository and raise it when relevance improves. The check runs in about three seconds and turns "search got worse" from an anecdote into a failing build.

Measured Impact

Before, the site used a Lunr index generated by a custom script. After, Pagefind with the boundary, weights and lazy UI:

MeasureLunr (before)Pagefind (after)
Index build time14.1 s4.9 s
First-query download (gzip)1.2 MB88 KB
Time to first result, Moto G Power, fast 4G2.7 s0.4 s
Queries ranked first (of 48)3341
JavaScript on pages without search open21 KB0 KB
Lighthouse Performance, docs template9399
Time to first search result on a mid-range phone Two stacked bars. With Lunr, the reader waited 2.7 seconds: 2.3 seconds downloading and parsing a 1.2 megabyte index and 0.4 seconds loading the library. With Pagefind, the reader waited 0.4 seconds: 0.25 seconds loading the library and WebAssembly and 0.15 seconds fetching 88 kilobytes of fragments. From opening search to the first result Lunr download + parse 1.2 MB index 2.7 s Pagefind 0.4 s library + WebAssembly 88 KB of fragments monolithic index Chrome DevTools, Moto G Power profile, fast 4G, cache disabled, median of 5
The whole difference is the index download: Pagefind fetches what the query needs, Lunr fetches everything first.

Tuning What Results Show

Relevance decides which page comes first; presentation decides whether the reader recognises it. Three small changes made the biggest difference on this site.

First, populate result metadata deliberately. By default Pagefind uses the first <h1> as the title and generates an excerpt around the match. Adding data-pagefind-meta="section:Guides" to the article and rendering it above the title in the result list lets readers tell apart the five pages titled "Configuration". Pagefind also picks up an image for each result if you mark one with data-pagefind-meta="image[src]"; for documentation this is usually noise, and leaving it out keeps the result list compact.

Second, keep sub-results on. With showSubResults: true, a long reference page contributes up to three heading-level matches, each linking to its anchor. In a two-week comparison, clicks on sub-results made up 34% of all result clicks, and those sessions had the lowest rate of a second search, which is the best proxy for "found it" that client-side analytics can give.

Third, set a sensible filter default. Once section is a filter, the UI shows it as a facet list. Pre-selecting nothing is correct for most sites, but for a product with separate user and admin docs, defaulting to the section the reader is currently browsing — read from the page's own data-pagefind-filter value — halves the number of irrelevant results without hiding anything, because the reader can clear the filter with one click.

Pitfalls & Rollback

  • No boundary. Everything in the nav matches every query. Add data-pagefind-body before judging relevance.
  • Long-cached entry file. Cache pagefind.js and pagefind-entry.json for minutes, not a year, or readers query yesterday's index after a deploy.
  • Missing CSP allowance. Pagefind compiles WebAssembly; a strict CSP needs 'wasm-unsafe-eval' in script-src or search fails silently.
  • Searching in dev. The index only exists after a build; test with astro preview, not astro dev.
  • Rollback: Pagefind is one build script suffix, one layout attribute set and one component. Removing the component hides search; removing the script suffix stops indexing. Content is untouched.

Conclusion

Pagefind turns search on an Astro site into a build step and three attributes. The boundary removes navigation noise, weights make titles count, lazy loading keeps the cost off every page view, and a CI query check keeps relevance from regressing. On this site that meant a first result in 0.4 seconds instead of 2.7, eight more queries answered correctly out of 48, and zero bytes of search code for the 94% of visitors who never search.

FAQ

Does Pagefind work in astro dev?

Not directly, because it indexes the built HTML. Run a production build once, copy the pagefind folder into public for development, or use an integration that serves a prebuilt index during dev. Search is usually tested against astro preview instead.

How big does the Pagefind index get?

The whole index on disk is roughly a quarter to a third of the site's text size, but a reader only downloads the fragments a query touches. On a 1,400-page Astro site the index folder was 11 MB and the first query downloaded 88 KB.

How do I stop the sidebar from being indexed?

Add data-pagefind-body to the element that wraps your main content. Once any page uses that attribute, Pagefind indexes only content inside it on every page, and ignores headers, sidebars and footers.

Can I show results in my own design instead of Pagefind UI?

Yes. Import pagefind.js directly and call search, then render the returned data yourself. The default UI is optional and costs about 30 KB of extra JavaScript and CSS.