Design Decisions

Design Decisions

The decisions that shape wiki-search, each with the alternative it beat and the research behind it.

D1 — Keep wikis open; bolt search on, don't migrate to Pages

Open GitHub wikis are proven safe at fleet scale (years, zero malicious edits — authenticated, reversible, accountable) and uniquely cheap for community fixes and experience-based how-tos. Search's value is real and achievable over the wiki without abandoning it. So the wiki stays canonical and we build a search appliance beside it — rather than migrating docs into GitHub Pages for the sake of search.

D2 — Path P (the popup) over inline injection or a plain redirect

window.open to our own origin is CSP-immune, so the bookmarklet stays a thin stub and all power/updatability lives on our origin. It beats:

• Inline injection (inject an engine into the GitHub page): CSP-constrained — inline-only engine, frozen at bookmark time, index-from-raw-only. Its one edge, in-place DOM highlighting, is mooted by Text Fragments anyway.
• A plain redirect page: loses the floating, no-context-lost feel of a popup.

The trade-off accepted: the popup is cross-origin to the wiki, so positioning rides on Text-Fragment links instead of DOM highlighting.

D3 — A self-describing, versioned index

The index carries its own site.urlTemplate, so result URLs are built mechanically with no hardcoded github.com. Clients validate (version + required fields) then use, else fail gracefully and explain. This is what makes the kit reusable beyond any one site. See Index Format.

D4 — Positioning via Text Fragments on real link clicks

#anchor:~:text=phrase — section anchor as a fallback plus phrase highlight where supported. Text Fragments fire only on user-initiated navigation, so results must be real <a> links, never scripted navigation.

D5 — Index in the wiki repo; deterministic builder; staleness gates

Hosted via raw.githubusercontent.com (in the wiki page CSP's connect-src, CORS *). Deterministic output (sorted, no timestamps) so CI git diff --exit-code can gate a stale index; a wiki pre-commit hook regenerates on edit.

D6 — A general-purpose tool, not a uhop-only one

Ships adoption docs and the index-format contract so anyone can incorporate it.

Research facts (live-probed 2026-06-04)

• GitHub wiki-page CSP connect-src includes raw.githubusercontent.com (plus api.github.com, 'self'); raw serves wiki files with access-control-allow-origin: * — so a bookmarklet/app can fetch a wiki-hosted index.
• script-src is github.githubassets.com only — no external scripts, no unsafe-eval, no wasm-unsafe-eval → Pagefind (WASM) is dead on-page; any in-page engine would have to be inline (mooted by Path P).
• No Document-Policy: force-load-at-top, so Text Fragments activate on wiki pages.
• Text Fragments: user-initiated navigation only; supported in Chrome/Edge, Safari 18.2+ (Dec 2024), Firefox 131+ (Oct 2024).
• javascript: bookmarklet execution is exempt from CSP (user-initiated); Firefox fixed its old bookmarklet-CSP bug (Bugzilla 866522).