Architecture

Architecture

wiki-search is four decoupled pieces around one self-describing artifact — the index. Nothing hardcodes GitHub; the index's own metadata drives every link.

Path P — the "Flip-It" popup

The hard constraint is the wiki page's Content-Security-Policy: no external scripts on the page itself. The workaround is to not run on the page at all.

The bookmarklet is a permanent, thin window.open stub. All logic lives in a search app hosted on our own origin (GitHub Pages). A window.opened window is a new top-level browsing context, so the host wiki page's CSP does not govern it — the app has full engine freedom and is updatable without re-saving the bookmark. This is the Flipboard "Flip It" pattern.

The cost: the popup is cross-origin to the wiki, so it can't reach into the page's DOM. Positioning therefore rides on link URLs (Text Fragments), not DOM manipulation.

The pieces

Piece	Role
builder/	wiki-index CLI: Markdown → a deterministic, self-describing index.
engine/	The search core — ranks sections for a query.
app/	The search page: loads + validates an index, searches, links to results.
bookmarklet/	The thin window.open stub + its minifier.

The index

A single JSON document with a version, a site block (name, urlTemplate, fragments), and a docs array of indexed sections. Result URLs are built purely from site.urlTemplate — see Index Format for the full contract.

The builder is deterministic (pages sorted, sections in document order, sequential ids, no timestamps), so a CI git diff --exit-code can detect a stale committed index.

Positioning — Text Fragments

Results are real <a> links carrying a Text Fragment directive: …/wiki/Page#anchor:~:text=phrase. The #anchor scrolls to the section; the :~:text= highlights the exact match where supported (Chrome/Edge, Safari 18.2+, Firefox 131+). Text Fragments fire only on user-initiated navigation, so results must be genuine link clicks, never scripted navigation — and the graceful fallback on older browsers is plain anchor scrolling.

Hosting & staleness

The index lives in the wiki repo and is served via raw.githubusercontent.com (which sits in the GitHub wiki page's CSP connect-src and sends access-control-allow-origin: *), so both the standalone app and any future inline client can fetch it cross-origin. A wiki pre-commit hook regenerates the index on edit, and the main repo's CI gates staleness with git diff --exit-code.