Pagefind for static site search, and how it compares with AdSense for Search
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.

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.
Why a static site needs a different kind of 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-bodyon 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-ignoreon 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
langattribute 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.
Pagefind vs AdSense for Search
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-bodyto 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-bodyon real content only.
Open-source tools mentioned
| Tool | Licence |
|---|---|
| Pagefind | MIT |
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
- Pagefind: Static low-bandwidth search at scale · Pagefind
- Getting Started with Pagefind · Pagefind
- Configuring what content is indexed · Pagefind
- Programmable Search Engine: About · Google
- Custom Search JSON API: Overview · Google for Developers
Related guides
- AdSense for Search: search ads on your site's results pages with Programmable Search Engine
How AdSense for Search shows Google search and Shopping ads on your site's results pages, how it relates to Programmable Search Engine, and who can still access it.
- Getting a static or Jamstack site approved for AdSense
Getting a static or Jamstack site approved for AdSense: where the code and ads.txt go, why platform subdomains and previews trip reviews, and what stays the same.
- Lighthouse and Lighthouse CI on ad-heavy pages: setup, budgets and measuring third-party impact
Run Lighthouse and Lighthouse CI on pages with AdSense: a tested config, third-party budgets, an ads-on vs ads-off comparison and how to read the results.
- Automated ad-placement audits with Playwright: screenshots, slot counts and fill status
Audit AdSense placements with Playwright without requesting ads: count slots, check reserved heights and ads.txt, take mobile screenshots, track fill status safely.