Search functionality

[x3ek]

Summary

Add search capability to find posts by keyword, accessible from the navbar on every page.

Options

Option A: Client-side Search (Recommended for small blogs)

• Generate JSON index at build/cache time (/search.json)
• Use lightweight JS library (Fuse.js, Lunr.js, or vanilla JS)
• No server required for search queries
• Fast, works offline

// /search.json
[
  {
    "title": "Grandma's Intergalactic Gumbo",
    "url": "/posts/intergalactic-gumbo",
    "tags": ["cooking", "aliens"],
    "excerpt": "When the Zorgblaxians landed...",
    "date": "2026-01-24"
  }
]

Option B: Server-side Search

• Endpoint: GET /search?q=gumbo
• SQLite FTS5 full-text search on cached content
• More powerful but requires server round-trip

Option C: External Service

• Algolia, Typesense, Meilisearch
• Most powerful, but adds complexity/cost

Recommendation

Start with Option A (client-side) for simplicity:

1. Add /search.json endpoint that returns post index
2. Use Fuse.js for fuzzy matching
3. Build the UI as a navbar search component (see below)

UI: Two Theme Modes

Themes can choose between two search UI modes in the navbar:

Button Mode

• Nav shows a search icon/button
• Clicking opens a dropdown popup with a search input + results list
• Useful for minimal navbars (e.g., terminal theme)

Input Mode

• Nav has a search input already inline in the navbar
• Typing opens a dropdown below it with results only (no duplicate input)
• Useful for themes with more spacious navbars (e.g., blue-tech)

Both modes share the same search logic and results dropdown component — the only difference is whether the input lives inline in the nav or inside the dropdown.

Shared Behavior

• Results list shows 5-8 matching posts, updates as you type
• Click a result to navigate to that post
• Escape or click outside closes the dropdown
• Cmd/Ctrl + K keyboard shortcut opens/focuses search (in button mode opens dropdown, in input mode focuses the input)

Implementation Notes

• Each theme's base.html chooses its mode via markup (button element vs input element with a shared data-search attribute or CSS class)
• The search JS detects which mode is in use and attaches behavior accordingly
• A shared results dropdown template/partial is used by both modes
• The search index (/search.json) and matching logic are theme-agnostic

Future Integration

When #32 (homepage/posts page redesign) is implemented, the posts page will also have an inline search bar that reuses the same search index and matching logic. The navbar search remains as the global quick-search.