Improve search functionality and reliability

[will-lamerton]

Summary

The documentation site has basic search functionality using Pagefind, but there's room to make it more reliable, useful, and feature-complete. This issue covers search improvements.

Current State

From components/ProjectSearch.tsx, the current search:

• Uses Pagefind for full-text search
• Has basic project categorization via badges
• Uses Headless UI Combobox for the UI
• Has basic result display with excerpts

Problem Areas

1. Project filtering - Search filters by project but may not be reliable
2. Result ranking - May not prioritize the most relevant results
3. Empty states - No helpful feedback when no results found
4. Keyboard navigation - May need improvement
5. Mobile experience - Search UI on mobile needs work
6. Search scope - Unclear if search covers all versions or just latest

Proposed Improvements

1. Better Project Filtering

Currently search may not properly filter by project:

• Ensure search only shows results for the selected project
• Add clear project indicator in search results
• Consider search across all projects as an option

// Better filtering
window.pagefind.debouncedSearch(query, {
  filters: {
    projectId: [currentProjectId]
  }
});

2. Enhanced Result Display

• Show more context in excerpts (surrounding keywords)
• Highlight matching terms in results
• Show page hierarchy in results
• Display version information

3. Search Statistics

• Show number of results found
• "No results" helpful message with suggestions

4. Keyboard Shortcuts

• Cmd/Ctrl + K to open search (common pattern)
• Arrow key navigation
• Enter to select
• Escape to close

5. Search Analytics (Optional)

• Track popular searches
• Identify gaps in documentation

6. Version-aware Search

• Clarify if search covers all versions or current version
• Option to search across all versions

Requirements

1. Reliable project filtering - Results match selected project
2. Better excerpts - More context, keyword highlighting
3. Keyboard shortcuts - Cmd/Ctrl+K to open
4. Empty state handling - Helpful "no results" message
5. Result count - Show number of results
6. Mobile-friendly - Works well on mobile

Files Likely Affected

• components/ProjectSearch.tsx - Main search component
• components/ui/command.tsx - May use shadcn command component
• app/layout.tsx - Add keyboard shortcut listener
• lib/pagefind-metadata.tsx - Already exists for indexing

Implementation Ideas

Keyboard Shortcut

// In root layout or search component
useEffect(() => {
  const handleKeyDown = (e: KeyboardEvent) => {
    if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
      e.preventDefault();
      setIsOpen(true);
    }
  };
  document.addEventListener('keydown', handleKeyDown);
  return () => document.removeEventListener('keydown', handleKeyDown);
}, []);

Result Highlighting

function HighlightedExcerpt({ excerpt, query }: { excerpt: string; query: string }) {
  const parts = excerpt.split(new RegExp(`(${query})`, 'gi'));
  return (
    <span>
      {parts.map((part, i) =>
        part.toLowerCase() === query.toLowerCase() ? (
          <mark key={i} className="bg-yellow-200">{part}</mark>
        ) : (
          part
        )
      )}
    </span>
  );
}

Success Criteria

• Search properly filters by project
• Keyboard shortcut (Cmd/Ctrl+K) opens search
• Results show relevant excerpts with context
• "No results" shows helpful message
• Arrow keys navigate results
• Search works well on mobile
• Clear indication of which project is being searched