diff --git a/docs/superpowers/specs/2026-07-02-wiki-search-result-badge-design.md b/docs/superpowers/specs/2026-07-02-wiki-search-result-badge-design.md new file mode 100644 index 0000000..44489ea --- /dev/null +++ b/docs/superpowers/specs/2026-07-02-wiki-search-result-badge-design.md @@ -0,0 +1,88 @@ +# Wiki Badge in Global Search Results — Theme Design + +Date: 2026-07-02 +Status: Approved for planning +Scope: theme-only slice of the cross-repo "wiki in global search" work. + +Companion spec (drives this): `sow-nodebb-plugin-wiki` → +`docs/superpowers/specs/2026-07-02-wiki-global-search-design.md`. The wiki +plugin makes wiki articles searchable and tags each wiki result with +`isWikiArticle: true` and `wikiPath` (`/wiki/...`). **This spec covers only the +rendering of those tagged results in the theme.** + +## Problem + +The theme currently ships no search-result overrides — global search +(quick-search dropdown + `/search` page) renders with stock NodeBB templates. +Once the wiki plugin surfaces wiki articles in search, those results need to be +visually marked as wiki and to link to `/wiki/...` instead of `/topic/...`. + +## Input contract (from the wiki plugin) + +Each search result object may carry: + +- `isWikiArticle` — `true` for wiki article hits. +- `wikiPath` — the `/wiki/...` URL for the article. + +Forum results do not carry these; they render unchanged. + +## Design + +Mark wiki result rows and point them at the wiki URL, in **both** surfaces: + +1. **`/search` page** — the full results list. +2. **Quick-search dropdown** — the navbar type-ahead results. + +For each row where `isWikiArticle` is set: + +- show a wiki icon/badge (e.g. a book/wiki icon plus a small "Wiki" label), + consistent with existing theme iconography (see `GAME_ICONS.md`); +- set the result's link `href` to `wikiPath`. + +Rows stay in the single relevance-ranked list returned by search; no grouping or +reordering. + +### Approach — decide during planning + +Two ways to inject this; pick the smaller one that works against the pinned +NodeBB version: + +- **Template override (preferred if a small partial isolates the row):** add a + theme override of the NodeBB search result partial(s) — the quick-search + results partial and the `/search` results partial — with a conditional badge + and `wikiPath` link. Keeps logic declarative and server-rendered. +- **Client-side decoration (fallback):** in `public/client.js`, after results + render, decorate rows flagged `isWikiArticle` (badge + rewrite href). Smaller + surface if the stock partials are awkward to override cleanly, but relies on + the data being present in the client payload. + +Planning resolves which, based on the actual stock partials in the pinned +NodeBB/theme base. + +## Styling + +Add badge styles in the theme SCSS (`scss/`, wired via `theme.scss`), matching +existing badge/pill conventions. No new dependencies. + +## Non-goals + +- No search *behavior* changes — indexing, matching, ranking, and result tagging + all live in the wiki plugin. +- No grouping/separate section — inline badge only. +- No changes to non-search surfaces. + +## Testing / verification + +- Visual: run the dev stack (`docker-compose.dev.yml` in `sow-nodebb`), search a + term matching a wiki article, confirm the result shows the wiki badge and its + link goes to `/wiki/...`; confirm forum results are unchanged. Check both the + dropdown and the `/search` page. +- Snapshot/DOM assertions only if the theme's existing test setup (`tests/`) + makes them cheap; otherwise rely on the visual check (badge/link is not + complex logic). + +## Dependencies / sequencing + +Depends on the wiki plugin emitting `isWikiArticle` + `wikiPath` on results. +Theme work can be built against a stubbed result but is only end-to-end +verifiable once the plugin side lands.