feat(docs): add search with Pagefind and Cmd+K shortcut (closes #5)

- Pagefind indexes all 28 doc pages at build time
- Search modal with Cmd+K / Ctrl+K keyboard shortcut
- Lazy-loads Pagefind JS on first search (no upfront cost)
- 200ms debounced input, up to 8 results with title + excerpt
- Search trigger in desktop nav (docs pages) and sidebar top
- Landing page excluded from index (data-pagefind-ignore)
- Styled with Terminal Green design tokens

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: michaelmcnees

site/package-lock.json

@@ -5,14 +5,15 @@
   "type": "module",
   "scripts": {
     "dev": "astro dev",
-    "build": "astro build",
+    "build": "astro build && npx pagefind --site dist",
     "preview": "astro preview"
   },
   "dependencies": {
     "@astrojs/mdx": "^5.0.2",
     "@astrojs/sitemap": "^3.7.1",
     "@tailwindcss/vite": "^4.2.2",
     "astro": "^6.0.8",
+    "pagefind": "^1.4.0",
     "tailwindcss": "^4.2.2"
   }
 }

site/package.json

@@ -0,0 +1,137 @@
+---
+---
+<div class="relative" id="search-container">
+  <button
+    id="search-trigger"
+    class="flex items-center gap-2 px-3 py-1.5 text-xs text-on-surface-variant border border-outline-variant bg-surface-container-low hover:border-outline transition-colors font-mono w-full lg:w-48"
+    type="button"
+  >
+    <svg class="w-3.5 h-3.5 shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+    </svg>
+    <span class="flex-1 text-left">Search docs...</span>
+    <kbd class="hidden lg:inline text-[10px] text-on-surface-variant/60 border border-outline-variant/50 px-1 rounded-sm">⌘K</kbd>
+  </button>
+</div>
+
+<!-- Search modal -->
+<div id="search-modal" class="fixed inset-0 z-[100] hidden">
+  <div class="fixed inset-0 bg-black/60 backdrop-blur-sm" id="search-backdrop"></div>
+  <div class="fixed top-[15%] left-1/2 -translate-x-1/2 w-full max-w-xl bg-surface-container border border-outline-variant shadow-2xl max-h-[60vh] flex flex-col">
+    <div class="flex items-center gap-3 px-4 py-3 border-b border-outline-variant">
+      <svg class="w-4 h-4 text-on-surface-variant shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+      </svg>
+      <input
+        id="search-input"
+        type="text"
+        placeholder="Search documentation..."
+        class="flex-1 bg-transparent text-on-surface text-sm outline-none placeholder:text-on-surface-variant/50 font-body"
+        autocomplete="off"
+      />
+      <kbd class="text-[10px] text-on-surface-variant/60 border border-outline-variant/50 px-1.5 py-0.5 rounded-sm">Esc</kbd>
+    </div>
+    <div id="search-results" class="overflow-y-auto p-2 text-sm">
+      <p class="px-3 py-4 text-on-surface-variant/60 text-center text-xs">Type to search...</p>
+    </div>
+  </div>
+</div>
+
+<script is:inline>
+function initSearch() {
+  const trigger = document.getElementById('search-trigger');
+  const modal = document.getElementById('search-modal');
+  const backdrop = document.getElementById('search-backdrop');
+  const input = document.getElementById('search-input');
+  const results = document.getElementById('search-results');
+  if (!trigger || !modal || !input || !results) return;
+
+  let pagefind = null;
+
+  async function loadPagefind() {
+    if (pagefind) return pagefind;
+    try {
+      pagefind = await import('/pagefind/pagefind.js');
+      await pagefind.init();
+    } catch (e) {
+      console.warn('Pagefind not available (run build first):', e);
+      pagefind = null;
+    }
+    return pagefind;
+  }
+
+  function openSearch() {
+    modal.classList.remove('hidden');
+    input.value = '';
+    input.focus();
+    results.innerHTML = '<p class="px-3 py-4 text-on-surface-variant/60 text-center text-xs">Type to search...</p>';
+  }
+
+  function closeSearch() {
+    modal.classList.add('hidden');
+  }
+
+  trigger.onclick = openSearch;
+  backdrop.onclick = closeSearch;
+
+  // Cmd+K / Ctrl+K shortcut
+  document.addEventListener('keydown', (e) => {
+    if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+      e.preventDefault();
+      if (modal.classList.contains('hidden')) openSearch();
+      else closeSearch();
+    }
+    if (e.key === 'Escape') closeSearch();
+  });
+
+  let debounceTimer;
+  input.addEventListener('input', () => {
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(async () => {
+      const query = input.value.trim();
+      if (!query) {
+        results.innerHTML = '<p class="px-3 py-4 text-on-surface-variant/60 text-center text-xs">Type to search...</p>';
+        return;
+      }
+
+      const pf = await loadPagefind();
+      if (!pf) {
+        results.innerHTML = '<p class="px-3 py-4 text-on-surface-variant/60 text-center text-xs">Search unavailable (build required)</p>';
+        return;
+      }
+
+      const search = await pf.search(query);
+      if (search.results.length === 0) {
+        results.innerHTML = '<p class="px-3 py-4 text-on-surface-variant/60 text-center text-xs">No results for &quot;' + query.replace(/[<>"&]/g, '') + '&quot;</p>';
+        return;
+      }
+
+      const items = await Promise.all(search.results.slice(0, 8).map(r => r.data()));
+      const container = document.createElement('div');
+      items.forEach(item => {
+        const link = document.createElement('a');
+        link.href = item.url;
+        link.className = 'block px-3 py-2 hover:bg-surface-container-high transition-colors group';
+
+        const title = document.createElement('div');
+        title.className = 'font-medium text-on-surface text-sm group-hover:text-primary transition-colors';
+        title.textContent = item.meta?.title || item.url;
+        link.appendChild(title);
+
+        const excerpt = document.createElement('div');
+        excerpt.className = 'text-xs text-on-surface-variant mt-0.5 line-clamp-2';
+        // Pagefind excerpt contains <mark> tags from our own build index — safe to render
+        excerpt.innerHTML = item.excerpt;
+        link.appendChild(excerpt);
+
+        link.addEventListener('click', closeSearch);
+        container.appendChild(link);
+      });
+
+      results.replaceChildren(...container.childNodes);
+    }, 200);
+  });
+}
+initSearch();
+document.addEventListener('astro:after-swap', initSearch);
+</script>

site/src/components/DocsSearch.astro

@@ -1,6 +1,7 @@
 ---
 import { docsNav } from '../data/docs-nav';
 import type { NavItem } from '../data/docs-nav';
+import DocsSearch from './DocsSearch.astro';
 
 interface Props {
   currentPath: string;
@@ -20,6 +21,9 @@ function isParentActive(item: NavItem): boolean {
 
 <aside id="docs-sidebar" class="docs-sidebar hidden lg:block w-60 shrink-0">
   <div class="sticky top-16 h-[calc(100vh-4rem)] overflow-y-auto py-8 pr-4 pl-2">
+    <div class="mb-6">
+      <DocsSearch />
+    </div>
     <nav aria-label="Documentation sidebar">
       {docsNav.map((group) => (
         <div class="mb-8">

site/src/components/DocsSidebar.astro

@@ -1,4 +1,6 @@
 ---
+import DocsSearch from './DocsSearch.astro';
+
 interface Props {
   isHome?: boolean;
 }
@@ -21,6 +23,13 @@ const isDocs = !isHome;
       <a href="/docs/getting-started" class:list={["text-sm transition-colors", isDocs ? "text-primary font-medium" : "text-on-surface-variant hover:text-on-surface"]}>Docs</a>
     </div>
 
+    <!-- Search (desktop, docs pages only) -->
+    {isDocs && (
+      <div class="hidden md:block">
+        <DocsSearch />
+      </div>
+    )}
+
     <!-- Right side -->
     <div class="flex items-center gap-4">
       <a href="https://github.com/dvflw/mantle" class="text-on-surface-variant hover:text-on-surface transition-colors" aria-label="GitHub">

site/src/components/Nav.astro

@@ -30,7 +30,7 @@ const { prev, next } = getPrevNext(currentPath);
 
       <!-- Main content -->
       <main id="main-content" class="flex-1 min-w-0 py-8 px-2 sm:px-6 lg:px-10">
-        <article class="prose max-w-3xl">
+        <article class="prose max-w-3xl" data-pagefind-body>
           <slot />
         </article>
 

site/src/layouts/Docs.astro

@@ -12,7 +12,7 @@ import Footer from '../components/Footer.astro';
 ---
 <Base title="Mantle — Headless AI Workflow Automation">
   <Nav isHome={true} />
-  <main id="main-content" class="pb-16 md:pb-0">
+  <main id="main-content" class="pb-16 md:pb-0" data-pagefind-ignore>
     <Hero />
     <Features />
     <HowItWorks />

site/src/pages/index.astro

@@ -157,6 +157,13 @@ body {
   opacity: 1;
 }
 
+/* Pagefind search result highlights */
+mark[data-pagefind-highlight] {
+  background-color: var(--color-primary);
+  color: var(--color-on-primary);
+  padding: 0 2px;
+}
+
 /* Scrollbar styling */
 ::-webkit-scrollbar {
   width: 8px;