Field note 3 — When demo pages pollute your search index

Original to this site (not upstream content). Measured during this site’s spike and production build, 2026-11-12.

Pagefind indexes the HTML it finds in your output directory — all of it, including standalone demo pages you copied next to your articles. During our two-base spike we diffed the index vocabulary against the guide texts and found 74 words that appear only inside demo files and in none of the 8 guide bodies. Search for one of those words and the reader lands on a bare demo fragment instead of a guide.

Three properties make this easy to miss:

1. The demos are legitimate pages (readers open them standalone), so you can’t just delete them from the output.
2. The pollution is invisible in the UI until someone searches an unlucky word.
3. Both framework-integrated and manual Pagefind runs behaved the same — it is a globbing problem, not a tooling bug.

The fix used here

• Demos live under a dedicated path prefix (/demos/…), separate from guide pages (/guides/…).
• The framework’s automatic indexing is disabled, and Pagefind is run explicitly with an index-only glob: demos are standalone files named demo.html / negative-demo.html, never index.html, so pagefind --site dist --glob "**/index.html" indexes exactly the site’s pages and structurally cannot pick up a demo. (This pagefind build accepts only one --glob; the path separation is what makes one glob sufficient.)
• Verification is part of the build, not a hope: pick words that occur only inside demo files, query the built index for them, and require zero hits — while a word from a guide body must still hit its guide. The exact probe words and results for this build are recorded in the project’s BUILD-REPORT.md.

If your demos can’t be path-separated, the alternative is marking demo documents with Pagefind’s ignore attributes — but then you are editing generated files, and the exclusion has to be re-applied on every sync. Path separation survives re-conversion for free.