The Architecture: Why Pagefind
Traditional search requires a running server — Elasticsearch, Algolia, Meilisearch — each with hosting costs, API key management, and latency from network round trips. For a static site, this is overkill.
Pagefind is different. It runs a compiled Rust binary at build time, parsing your HTML and chunking keywords into tiny cached fragments. When a user searches, the browser downloads only the specific fragments needed — usually under 30KB total. Zero backend. Zero infrastructure. Zero latency.
Traditional Search (Algolia/Elasticsearch):
- User types → Network request → Server queries index → Response → Render
- Latency: ~50-200ms round trip
Pagefind (Static):
- User types → Local WASM index → Instant results → Render
- Latency: ~1-5ms local execution
Step 1: Installation & Build Automation
Install Pagefind
Tell your AI tool:
“Add Pagefind as a dev dependency. Update the build script to run Pagefind after the static build: astro build && pagefind --site dist”
Configure the Build Script
Append Pagefind to your static build command. It runs after your site is built, parsing the output HTML.
Tell your AI tool:
“Configure the build script to run Pagefind after Astro build: astro build && pagefind --site dist. Add a search:dev script that runs Pagefind’s local server at localhost:1414 for testing.”
The search:dev script runs Pagefind’s local server so you can test search without deploying. It serves the built site at localhost:1414 with search enabled.
Astro Configuration
Tell your AI tool: “Configure Astro with MDX integration and Shiki syntax highlighting. Set the site URL and use directory output format for Pagefind compatibility.”
Step 2: Content Targeting
By default, Pagefind indexes your entire page — including navbars, footers, and sidebars. This creates noisy results. You need to tell Pagefind exactly what content to index.
Mark Indexable Content
Add data-pagefind-body to your main content wrapper. Only content inside this attribute gets indexed.
Tell your AI tool: “Add data-pagefind-body attribute to the main content element in the layout. The sidebar and footer should NOT have this attribute — they won’t be searchable. Only the article content inside main should be indexed.”
Fine-Grained Control
| Attribute | Purpose | Example |
|---|---|---|
data-pagefind-body | Mark indexable content area | <main data-pagefind-body> |
data-pagefind-weight="2" | Boost importance (default: 1) | <h1 data-pagefind-weight="2">Title</h1> |
data-pagefind-weight="0.5" | Reduce importance | <aside data-pagefind-weight="0.5">Sidebar</aside> |
data-pagefind-exclude | Exclude element and children | <div data-pagefind-exclude>Hidden content</div> |
data-pagefind-meta="title" | Extract metadata for results | <h1 data-pagefind-meta="title">Page Title</h1> |
data-pagefind-filter="type:guide" | Add filterable facets | <article data-pagefind-filter="type:guide"> |
Excluding Navigation from Results
Tell your AI tool: “Add data-pagefind-exclude to navigation elements so they don’t appear in search results. The nav should be visible but not searchable.”
Step 3: The Command Palette Component
This is the full-featured search component with keyboard shortcuts, debouncing, arrow-key navigation, and responsive design.
Tell your AI tool: “Create a command palette search component with:
- Full-screen overlay with blur backdrop
- Search input with magnifying glass icon and ESC badge
- Status bar showing result count
- Results list with title, section, and excerpt
- Footer with keyboard navigation hints (↑↓ Navigate, ↵ Open, ESC Close)
- Mobile responsive (slides up from bottom on small screens)
- Accessibility: ARIA labels, live regions, keyboard navigation”
The component should be fully styled with your design system colors and ready to drop into any Astro page. This replaces the full HTML/CSS/JS implementation — your AI tool generates the actual component code.
Step 4: Trigger Button in the Sidebar
Add a search trigger button that opens the command palette. This should be visible in the sidebar header and respond to the same Cmd+K shortcut.
Tell your AI tool: “Create a search trigger button in the sidebar with:
- Text: ‘Search playbook…’
- Keyboard shortcut badge: ⌘K
- Styled with surface background, subtle border, 8px border-radius
- Hover: border becomes stronger
- Focus: accent color border with glow
- On click: opens the search overlay and focuses the input”
The button should be styled with your design system colors and wire up to the search overlay component.
Step 5: Verification & Testing
Build and Verify
# Build the site + generate search index
npm run build
# Verify Pagefind output exists
ls dist/pagefind/
# Expected files:
# pagefind.js — Main search WASM (~30KB)
# pagefind-entry.json — Index metadata
# fragment/ — Chunked text fragments
# wasm/ — Compiled search binary
Test Locally
# Run Pagefind's local server
npx pagefind --site dist --serve
# Opens at http://localhost:1414
# Test search: type "token", "RAG", "Docker"
Verify Index Quality
Check what Pagefind actually indexed:
# Generate a search summary
npx pagefind --site dist --logfile pagefind-log.json
# The log shows:
# - Number of pages indexed
# - Number of fragments generated
# - Total index size
Common Issues
| Symptom | Cause | Fix |
|---|---|---|
| Search returns nothing | Pagefind not run after build | Add && pagefind --site dist to build script |
| Navigation items in results | Missing data-pagefind-exclude | Add exclusion attribute to nav/footer |
| Results show raw HTML tags | Content not properly rendered | Ensure data-pagefind-body is on rendered content |
| Search is slow on first query | WASM not cached | Normal for first load; subsequent queries are instant |
| Index is huge (>500KB) | Too much content indexed | Use data-pagefind-exclude to trim non-essential pages |
Key Takeaways
| Concept | Mental Model | Senior Insight |
|---|---|---|
| Static Search | WASM binary runs locally in browser | Zero server cost, zero latency, zero API keys |
| Content Targeting | data-pagefind-body marks indexable regions | Exclude nav/footer to avoid noisy results |
| Weight & Metadata | Boost importance, extract titles | Use data-pagefind-weight to rank critical content higher |
| Command Palette | Cmd+K opens search overlay | Keyboard navigation (↑↓ Enter ESC) is expected UX |
| Debouncing | Wait 200ms after last keystroke | Prevents searching on every single character |
| Lazy Loading | Import Pagefind WASM on first focus | Zero JS cost until the user actually wants to search |