CYDERCODER // PLAYBOOK
SYS.STATUS: OK 00%
> INITIALIZING...
Install this playbook for offline access
You're offline — reading cached content
WHO THIS IS FOR

Built for every stage of the builder journey

Beginners

Clear path from zero to deployed product in one afternoon. Exact AI prompts to copy. Explains the why, not just the how — all the way to production with a custom domain.

  • Build your first website end-to-end
  • Deploy with Vercel, set up Google Search Console
  • Understand what React is doing behind the scenes

Senior Devs

A reference manual for AI architecture decisions. RAG chunking, MCP, multi-agent systems, CDN caching, deployment strategies — without the fluff.

  • RAG chunking strategies, MCP protocol architecture
  • Typography scale, color theory, motion design systems
  • CDN caching, edge functions, deployment strategies
Portrait Lock Active
Please rotate your device back to Portrait orientation to read the playbook content.
Back to Dashboard

Zero-Latency Static Search: Pagefind Integration

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

AttributePurposeExample
data-pagefind-bodyMark 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-excludeExclude 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

SymptomCauseFix
Search returns nothingPagefind not run after buildAdd && pagefind --site dist to build script
Navigation items in resultsMissing data-pagefind-excludeAdd exclusion attribute to nav/footer
Results show raw HTML tagsContent not properly renderedEnsure data-pagefind-body is on rendered content
Search is slow on first queryWASM not cachedNormal for first load; subsequent queries are instant
Index is huge (>500KB)Too much content indexedUse data-pagefind-exclude to trim non-essential pages

Key Takeaways

ConceptMental ModelSenior Insight
Static SearchWASM binary runs locally in browserZero server cost, zero latency, zero API keys
Content Targetingdata-pagefind-body marks indexable regionsExclude nav/footer to avoid noisy results
Weight & MetadataBoost importance, extract titlesUse data-pagefind-weight to rank critical content higher
Command PaletteCmd+K opens search overlayKeyboard navigation (↑↓ Enter ESC) is expected UX
DebouncingWait 200ms after last keystrokePrevents searching on every single character
Lazy LoadingImport Pagefind WASM on first focusZero JS cost until the user actually wants to search