Search issues

What to check when Pagefind search returns no results, shows stale content, or fails to load entirely. Covers index generation, deployment, and browser-side issues.

Pagefind is Project Broadsheet's search engine. It indexes your site at build time and runs entirely in the reader's browser. Most search problems come from one of three places: the index never generated, the index is out of date, or the script can't load in the browser.

Symptom: search returns no results

Check 1 — Is the index generated?

ls _site/pagefind/

You should see pagefind.js, pagefind-ui.js, pagefind-ui.css, and several .pf_fragment files.

If _site/pagefind/ is missing or empty, Pagefind didn't run. The most common cause: you ran npm start (dev server) instead of npm run build (production). Pagefind only runs on production builds. Run:

npm run build

And check again.

Check 2 — Does the live site have the index?

Even if local build generates the index, the deployed site might not. Check:

https://yoursite.com/pagefind/pagefind.js

You should see a minified JavaScript file. If you get a 404, the pagefind/ folder didn't deploy. Common causes:

• .gitignore excludes _site/. The build folder isn't committed; it's regenerated by the host. Confirm the host runs npm run build (not npx eleventy alone) in its build command.
• The host is caching the old version. Force a fresh deploy.

Check 3 — Is the UI script loading?

Open the browser's dev tools (Network tab) and look for pagefind-ui.js. If it's blocked or 404ing, the <script> tag is pointing at the wrong URL. Project Broadsheet expects it at /pagefind/pagefind-ui.js (root-relative).

Symptom: new articles aren't appearing in search

The index is stale. Pagefind regenerates only on production builds, so:

1. Commit and push your changes.
2. Wait for the host to deploy.
3. Hard-refresh the search page (Cmd+Shift+R / Ctrl+Shift+R).

If the deploy succeeded but the index is still stale, the host may be caching the old pagefind/ folder. On Cloudflare Pages, purge the cache in the project settings. On Netlify and Vercel, a fresh deploy is usually enough.

Symptom: search suggests results but clicking does nothing

Pagefind generates URLs at index time. If you ran the build with one meta.url value and deployed under a different domain, the links will point at the wrong host.

Fix:

1. Confirm meta.url in src/_data/meta.js matches the live domain.
2. Rebuild and redeploy.

Symptom: search UI styling looks broken

The Pagefind UI CSS is a separate stylesheet. If it's blocked or failing to load, the search interface renders unstyled.

1. Check the Network tab for /pagefind/pagefind-ui.css.
2. If blocked, check Content Security Policy (CSP) headers — they may disallow external stylesheets.

Project Broadsheet also sets CSS variables to skin Pagefind's UI. If those aren't applying, the #pagefind-search element may be missing from the page. Confirm the docs hub includes:

<div id="pagefind-search"></div>

Symptom: search is very slow

Pagefind is extremely fast on small sites (hundreds of articles). If it's slow:

• Check network conditions. The browser fetches fragments on each query. Slow connections feel the drag.
• Profile the index size. Run ls -lah _site/pagefind/ and check the total size. Over 10 MB indicates a lot of content; consider trimming with data-pagefind-ignore attributes.

Exclude parts of a page from the index

Add data-pagefind-ignore to any element Pagefind shouldn't index:

<aside data-pagefind-ignore>
  Content that shouldn't appear in search results.
</aside>

Useful for sidebars, footers, repeated boilerplate.

What to do next

• Pagefind search setup for full configuration.
• Build errors if Pagefind is failing during the build.
• Deployment: Cloudflare Pages for host-specific deploy notes.