Overview

Overview

The problem

Open GitHub wikis are uniquely good for documentation: anyone can fix a typo or add an experience-based how-to, edits are authenticated, reversible, and accountable, and the open-edit model has proven safe at fleet scale. But wikis have no real search — GitHub's built-in wiki search is weak, and you can't bolt a search engine onto a wiki page because GitHub serves it under a strict Content-Security-Policy that blocks external scripts, eval, and WebAssembly (so client-side engines like Pagefind are dead on-page).

Search matters because it decouples findability from information architecture: readers stop depending on perfect page organization, and the person who inherits a project can find the one paragraph they need.

The idea

Don't migrate docs into something more searchable — keep the wiki and bolt search beside it. wiki-search is three small, decoupled parts:

1. A builder turns a wiki's Markdown into a compact, versioned JSON index.
2. The index is self-describing: it carries its own site.urlTemplate, so result links are built mechanically with no hardcoded host.
3. A search app (and a one-line bookmarklet) loads that index, searches it, and links to the matching section — highlighting the exact phrase where the browser supports it.

The guiding principle

Assume nothing; explain everything. A client validates the index's version and required fields, then uses it — and on any failure (missing index, bad JSON, unsupported version, missing fields) it shows a specific message rather than a blank result box. Because the contract is self-describing and versioned, anyone can adopt it: generate an index from your docs, host it anywhere CORS-readable, and point the app at it. wiki-search is not GitHub-specific — a non-GitHub site just ships a different urlTemplate.

See Architecture for how the pieces fit together, and Design Decisions for why it's built this way.