Open data & tools

Pagefind for static site search, and how it compares with AdSense for Search

Last updated Published By the editorial team6 min5 sources

Key takeaways

  • Pagefind is an MIT-licensed search library that indexes your built HTML after the static site generator runs and serves search entirely from static files, with no server.
  • Version 1.6.0 was current in November 2026; since version 1.5 the Component UI (pagefind-modal and related web components) is the recommended interface, while the older Default UI is still supported.
  • Pagefind states that a 10,000-page site can be searched with under 300kB of total network payload, closer to 100kB for most sites.
  • data-pagefind-body and data-pagefind-ignore keep menus, footers and ad slots out of the index, which we verified on a test site.
  • Programmable Search Engine is the Google alternative: free, ad-supported and monetizable with AdSense, while the Custom Search JSON API is closed to new customers.
Jigsaw puzzle pieces fitting together
Image: Red jigsaw puzzle pieces,Profpcde,CC0,via Wikimedia Commons.

Pagefind adds full-text search to a static site without a server: it reads your built HTML after the generator runs and writes a chunked search index next to it. It is free, MIT-licensed and works with any static generator. For an AdSense site it is the no-ads, no-API alternative to Google’s Programmable Search Engine, which can show search ads through AdSense for Search.

A static site (Astro, Hugo, Eleventy, Jekyll, plain HTML) has no database to query. The usual options are:

  • A hosted search service, which costs money or shows its own ads.
  • Google’s Programmable Search Engine, free and ad-supported.
  • A client-side index that ships with the site. Pagefind is in this category.

The Pagefind homepage explains that the index is split into chunks, so a search only loads a small subset of it. It states that a 10,000-page site can be searched with a total network payload under 300kB, including the library itself, and “closer to 100kB” for most sites. That is the project’s own claim; measure it on your site.

The code is on GitHub under the MIT licence, and 1.6.0 was the current version on npm when this guide was written.

Step 1: add the search interface

The getting started guide adds the UI first, so it exists in the built site when Pagefind indexes it. Since version 1.5 the recommended interface is the Component UI, a set of web components:

<link href="/pagefind/pagefind-component-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-component-ui.js" type="module"></script>

<pagefind-modal-trigger></pagefind-modal-trigger>
<pagefind-modal></pagefind-modal>

The two files do not exist yet: Pagefind creates them in /pagefind/ when it indexes the site. The documentation also lists other components (pagefind-searchbox, pagefind-input, pagefind-results, pagefind-filter-pane and more) if you want an inline search page instead of a modal. The older “Default UI” (new PagefindUI({ element: "#search" })) is still documented and supported, but no longer the main recommendation, so many older tutorials show it.

Step 2: index the built site

Build your site, then run Pagefind on the output folder:

npx -y pagefind --site dist

Use the folder your generator writes to (dist for Astro, public for Hugo, _site for Eleventy). Add --serve to preview the result locally. The docs also show a Python wrapper (python3 -m pip install 'pagefind[extended]') and precompiled binaries.

In a project, chain it after the build in package.json:

{
  "scripts": {
    "build": "astro build && pagefind --site dist"
  }
}

That assumes pagefind is installed as a dev dependency (npm install -D pagefind).

What our test run produced

We ran npx -y pagefind@1.6.0 --site dist on a three-page test site in which one page contained an ad slot wrapped in data-pagefind-ignore. The output, shortened:

Running Pagefind v1.6.0 (Extended)
Found 3 files matching **/*.{html}
Found a data-pagefind-body element on the site.
↳ Ignoring pages without this tag.
Discovered 1 language: en
  Indexed 3 pages
  Indexed 21 words
  Indexed 1 filter
Finished in 0.295 seconds

The output folder was 655 kB on disk, including the WebAssembly search engine, several UI bundles and the index. A visitor only downloads what the page and the query need. For example, pagefind-component-ui.js was 184 kB and pagefind.js 47 kB before compression.

Step 3: keep ads, menus and boilerplate out of the index

This is where an ad-supported site needs a little care. Without guidance, Pagefind indexes from the <body>, so repeated elements can end up in results. The indexing documentation gives two attributes:

  • data-pagefind-body on your main content element limits indexing to that element. Once this attribute appears on any page of the site, pages without it are not indexed at all. Our test run printed exactly that warning.
  • data-pagefind-ignore on an element excludes it from the index. It defaults to ignoring the text content (index); data-pagefind-ignore="all" also ignores filters, metadata and everything else inside.

Pagefind also skips nav, footer, script and form elements automatically.

For ad slots, wrap the unit:

<main data-pagefind-body>
  <h1>Sourdough starter</h1>
  <p>Feed your starter with flour and water every day.</p>

  <div class="ad-slot" data-pagefind-ignore>
    <ins class="adsbygoogle" data-ad-client="ca-pub-XXXXXXXXXXXXXXXX" data-ad-slot="1234567890"></ins>
  </div>
</main>

Pagefind indexes the static HTML, not the page after JavaScript runs, so ad creatives are never in the index. What can leak in is static text around the slot, such as an “Advertisement” label or a fallback message. In our test, a placeholder label inside the ignored wrapper did not appear in the indexed content for that page.

Two other features matter for content sites:

  • Filters: add data-pagefind-filter="category" to an element and its text becomes a filter value. Our test indexed one filter this way.
  • Multilingual sites: Pagefind reads the lang attribute of each page and builds a separate index per language.

Building your own results page with the search API

If the components do not fit your design, the search API lets you query the index from your own JavaScript:

const pagefind = await import('/pagefind/pagefind.js');
const search = await pagefind.search('starter');
const first = await search.results[0]?.data();
console.log(search.results.length, first?.url, first?.meta.title, first?.excerpt);

The documentation explains the design: search() returns only result IDs, and each result’s URL, title and excerpt are loaded separately with data() to save bandwidth, so load only the first page of results. By default the title comes from the first h1 on the page, which matched what we saw in our test index. A custom results page is also the place to reserve space for any ad unit you show next to results, so the list does not jump when the ad loads.

AdSense for Search shows ads on your site’s search results pages through Google’s Programmable Search Engine. Here is how the two approaches compare, based on the Programmable Search Engine page and the Custom Search JSON API overview:

Pagefind Programmable Search Engine
Cost free, MIT licence free (ad-supported), paid ad-free option
Revenue none from search itself can be monetized with AdSense (AdSense for Search)
Where results come from your built HTML, indexed at build time Google’s index of your site
New pages searchable after the next build after Google crawls them
Server or API none Google-hosted
Look and feel your CSS and components Google’s element, with styling options

A point to note if you were planning a custom integration: Google’s overview states that the Custom Search JSON API is closed to new customers, that existing customers have until January 1, 2027 to move to an alternative, and it suggests Vertex AI Search. While it lasts, the API gives 100 free queries per day and then costs $5 per 1,000 queries, up to 10,000 per day. The embeddable Programmable Search Engine element is a separate product.

How to choose

  • You want the search page to earn money: Programmable Search Engine with AdSense for Search. See AdSense for Search for setup and limits.
  • You want fast, private, ad-free search that you control: Pagefind. Your regular AdSense units still appear on the search page like on any other page.
  • Your site is new and barely indexed by Google: Pagefind works from day one, since it does not depend on Google’s index.

If your site is static and you are still preparing for review, the static and Jamstack sites guide covers what matters for approval. A search box helps navigation, but it does not replace clear menus and internal links.

Testing the result

  • Run a few real queries after each build and check excerpts for menu text, cookie banner text or ad labels.
  • Measure the search page with Lighthouse; load the UI only where search appears.
  • Add the search page to your Playwright audit so a template change that breaks the components shows up in screenshots.

Common mistakes

  • Running Pagefind before the build finishes, or on the source folder instead of the output folder.
  • Adding data-pagefind-body to one template only: every page without it silently drops out of search.
  • Following an old tutorial that uses the Default UI and expecting the Component UI options to apply.
  • Committing the generated /pagefind/ folder instead of creating it on each build.
  • Indexing tag and pagination pages that add noise. Exclude them with data-pagefind-body on real content only.

Open-source tools mentioned

ToolLicence
PagefindMIT

Frequently asked questions

Does Pagefind show ads in search results?

No. Pagefind is a search library that runs from your own static files and has no ads or monetization of its own. Your normal AdSense units on the search page keep working like on any other page, provided the page has real content and follows the placement policies. If you want ads inside search results, that is what AdSense for Search with Programmable Search Engine is for.

Will Pagefind slow down my pages?

Only the page that shows the search interface loads its scripts, and the index is split into chunks that load as people type. On our three-page test site the Component UI script was about 184 kB uncompressed, and the full output folder was 655 kB, most of which a visitor never downloads. Load the UI only where search appears and test with Lighthouse.

Does Pagefind work with Astro, Hugo or Eleventy?

Yes. Pagefind works with any folder of static HTML, so it runs after any generator. You add one command after the build, pointing --site at the output folder, for example public for Hugo or dist for Astro. Wrapper packages exist for npx and Python, and there are precompiled binaries if you have neither installed.

Can I stop ad text from appearing in search excerpts?

Yes. Wrap ad containers in an element with data-pagefind-ignore, or put data-pagefind-body on your main content so everything outside it is skipped. Pagefind also skips nav, footer, script and form elements automatically. In our test, the placeholder text inside an ignored ad wrapper did not appear in the indexed content.

Sources

  1. Pagefind: Static low-bandwidth search at scale · Pagefind
  2. Getting Started with Pagefind · Pagefind
  3. Configuring what content is indexed · Pagefind
  4. Programmable Search Engine: About · Google
  5. Custom Search JSON API: Overview · Google for Developers