Site Search — Implementation Plan

Goal: Let visitors search across all WatchTheStars pages and posts (~300 pages: 108 blog posts + ~190 other pages).

Chosen approach: Pagefind — a static-site search library that indexes the built HTML at deploy time and runs entirely in the browser. No backend, no third-party account, no cost. Fits the existing Eleventy + Cloudflare Pages "build and push" workflow.

(This is a planning doc for review — it lives at the repo root and should not be deployed. Delete or move it once we've agreed the approach.)

Why Pagefind (vs. the alternatives)

Option	Verdict
Pagefind	✅ Auto-indexes built HTML, downloads index in small chunks per query, ships a themeable UI, zero backend/cost. Best fit.
Lunr.js / Fuse.js	❌ Loads the whole index upfront; doesn't scale well past ~100 pages; hand-rolled indexing + UI.
Algolia DocSearch	⚠️ Powerful + free tier, but adds an external account, a crawler to configure, and a dependency. Overkill here.
Cloudflare Worker + D1/Vectorize	⚠️ Only worth it for true semantic search; real backend to build + maintain. Park as a future enhancement.

How it slots into the current build

Current chain (run by Cloudflare on every push to main):

npm run build   →  eleventy  (renders _site/)
                →  postbuild: node scripts/minify.mjs  (PurgeCSS + clean-css + terser on _site/)

Pagefind runs last, after minify, so:

it indexes the final minified HTML, and
PurgeCSS never sees Pagefind's own CSS (it's generated into _site/pagefind/ after purge runs), so there's no risk of purging the search UI styles.

New chain:

npm run build   →  eleventy
                →  postbuild: node scripts/minify.mjs && npx pagefind --site _site

Implementation steps

1. Add the dependency

Add pagefind to devDependencies so Cloudflare installs it during npm install.
Update the postbuild script to append && npx pagefind --site _site.
Confirm the Cloudflare Pages build still succeeds (Node is available there; npx pagefind uses the locally installed binary).

2. Tell Pagefind what to index (the quality step)

By default Pagefind indexes the whole <body>, which would pull in nav, footer, and the email signup widgets — noisy results. Fix by editing the shared layouts:

Add data-pagefind-body to the main content container in each layout (blog-post-enhanced.njk, planet-enhanced.njk, uap-feature.njk, and the base/homepage layout).
Add data-pagefind-ignore to nav.njk, footer.njk, and the tonight-signup.njk widget so they're excluded everywhere.
Map result metadata from frontmatter: data-pagefind-meta="title" on the heading and an image meta tag, so results show a proper title + thumbnail.

3. Add the search UI

Put a search icon/button in nav.njk (next to BLOG / UAP RESEARCH).
Use Pagefind's bundled UI (/pagefind/pagefind-ui.js + CSS) opened in a modal/overlay.
Lazy-load it: only fetch the Pagefind UI script when the user clicks the search icon, so it adds zero weight to normal page loads.
Style the trigger to match the site (the results UI is themeable via CSS variables to fit the dark astronomy theme).
Mobile: place the icon so it works inside the existing responsive nav.

4. Optional polish (v2, not required for launch)

Category filter: expose categorySlug (astronomy / uap) as a Pagefind filter so users can narrow results.
Dedicated /search/ page for a full-page results view (in addition to the nav modal), useful for "no results" deep links.
Wire a GA4 event on search submit to see what people look for.

5. Test before deploy

Local: npm run build, then serve _site/ with the Python HTTP server and run real queries (e.g. "Jupiter", "Varginha", "meteor shower", a misspelling to confirm typo tolerance).
Check the generated index size under _site/pagefind/ (expected: small — tens of KB downloaded per search, not the whole index).
Confirm nav/footer/signup text does NOT appear in results.
Confirm a brand-new post is indexed automatically with no manual step.

6. Deploy

Push via the standard GitHub workflow in CLAUDE.md; Cloudflare rebuilds and the index regenerates on every deploy automatically.

What this changes / watch-items

No manual index upkeep — every new post/page is indexed on the next build automatically.
Build time rises slightly (Pagefind indexing ~300 pages is fast, a few seconds).
PurgeCSS interaction: any classes we add for the search trigger button live in the HTML, so PurgeCSS keeps them. The Pagefind results UI brings its own CSS from /pagefind/, untouched by purge. Verify once after first deploy.
No SEO impact: results render client-side; the /pagefind/ folder is just assets.

Rough effort

Roughly half a day end-to-end: ~1 hr wiring the build + dependency, ~1–2 hrs on layout data-pagefind-* attributes and the nav UI/styling, the rest on testing across page types. The optional v2 polish is separate.

Open questions for Ian

Placement — search icon in the main nav bar (my default), or also a bigger search box on the homepage / blog index?
Scope — index everything (all 300 pages), or restrict to blog posts + key hub pages?
v2 filters — do you want the astronomy/UAP category filter and GA4 search tracking now, or launch simple first?