wiki-search-index 0.1.0 → 0.1.2

package/INDEX-FORMAT.md

@@ -28,19 +28,19 @@ that emits this shape is searchable — wiki-search is not GitHub-specific.
 
 ## Fields
 
-| Field | Meaning |
-|-------|---------|
-| `v` | Format version. This document is `1`. Clients reject versions they don't understand. |
-| `site.name` | Human label for the corpus (shown in the UI). |
-| `site.urlTemplate` | Result-URL template; **must contain `{page}`**. No hardcoded host. |
-| `site.fragments` | `true` if the target renders [Text Fragments](https://developer.mozilla.org/docs/Web/Text_fragments). When `false`, clients omit the `:~:text=` directive. |
-| `docs[]` | One entry per indexed section. |
-| `doc.id` | Stable integer, sequential in build order. |
-| `doc.page` | The `{page}` substitution — for GitHub wikis, the page's URL segment (`Foo-Bar`). |
-| `doc.title` | Page display title. |
-| `doc.heading` | Section heading (falls back to the page title for a page's preamble). |
-| `doc.anchor` | In-page anchor slug; `""` means the page top. For GitHub, the heading's slug. |
-| `doc.text` | Plain-text body of the section (markdown stripped), for the search engine. |
+| Field              | Meaning                                                                                                                                                    |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `v`                | Format version. This document is `1`. Clients reject versions they don't understand.                                                                       |
+| `site.name`        | Human label for the corpus (shown in the UI).                                                                                                              |
+| `site.urlTemplate` | Result-URL template; **must contain `{page}`**. No hardcoded host.                                                                                         |
+| `site.fragments`   | `true` if the target renders [Text Fragments](https://developer.mozilla.org/docs/Web/Text_fragments). When `false`, clients omit the `:~:text=` directive. |
+| `docs[]`           | One entry per indexed section.                                                                                                                             |
+| `doc.id`           | Stable integer, sequential in build order.                                                                                                                 |
+| `doc.page`         | The `{page}` substitution — for GitHub wikis, the page's URL segment (`Foo-Bar`).                                                                          |
+| `doc.title`        | Page display title.                                                                                                                                        |
+| `doc.heading`      | Section heading (falls back to the page title for a page's preamble).                                                                                      |
+| `doc.anchor`       | In-page anchor slug; `""` means the page top. For GitHub, the heading's slug.                                                                              |
+| `doc.text`         | Plain-text body of the section (markdown stripped), for the search engine.                                                                                 |
 
 ## Building a result URL
 

package/README.md

@@ -1,4 +1,7 @@
-# wiki-search
+# wiki-search [![NPM version][npm-img]][npm-url]
+
+[npm-img]: https://img.shields.io/npm/v/wiki-search-index.svg
+[npm-url]: https://npmjs.org/package/wiki-search-index
 
 GitHub wikis are great for docs but have no real search. **wiki-search adds it:**
 a bookmarklet (plus a hosted search page) that searches a wiki and takes you
@@ -36,19 +39,27 @@ its own URL template, so the same app works for any site with no hardcoded host.
 <details>
 <summary>Repo layout & local run</summary>
 
-| Path | What |
-|------|------|
-| `index.html` | Landing + bookmarklet-install page (the Pages root). |
-| `app/` | The search page (loads + validates an index, searches, links out). |
-| `builder/` | `wiki-index` CLI: Markdown → the JSON index. |
-| `engine/` | Search core: MiniSearch (vendored), with a zero-dep fallback. |
-| `bookmarklet/` | The `window.open` stub + builder. |
+| Path           | What                                                                |
+| -------------- | ------------------------------------------------------------------- |
+| `index.html`   | Landing + bookmarklet-install page (the Pages root).                |
+| `app/`         | The search page (loads + validates an index, searches, links out).  |
+| `builder/`     | `wiki-index` CLI: Markdown → the JSON index.                        |
+| `engine/`      | Search core: MiniSearch (vendored), with a zero-dep fallback.       |
+| `bookmarklet/` | The bookmarklet — one constant, imported by the app + install page. |
 
 Run locally: `python3 -m http.server` from the repo root, then open
 <http://localhost:8000/app/?wiki=uhop/wiki-search>.
 
 </details>
 
+## Release notes
+
+- 0.1.2 _Fix: the published CLI was missing its execute bit, so `npx wiki-search-index` failed — now runnable._
+- 0.1.1 _HTML entities (`&mdash;`, `&#1234;`, …) are decoded so they no longer pollute the index._
+- 0.1.0 _Initial release of the `wiki-search-index` builder._
+
+For the full history see the wiki: [Release notes](https://github.com/uhop/wiki-search/wiki/Release-notes).
+
 ## License
 
 [BSD-3-Clause](LICENSE)

package/builder/README.md

@@ -13,14 +13,14 @@ node builder/wiki-index.mjs --wiki ./wiki --stdout        # print instead of wri
 node builder/wiki-index.mjs --wiki ./docs --url-template 'https://example.com/d/{page}' --name 'Example docs'
 ```
 
-| Flag | Default | Meaning |
-|------|---------|---------|
-| `--wiki <dir>` | `./wiki` | Markdown source directory. |
-| `--out <path>` | `<wiki>/search-index.json` | Where to write. |
-| `--stdout` | — | Print the index instead of writing a file. |
-| `--url-template <tpl>` | inferred | Result-URL template; must contain `{page}`. |
-| `--repo <owner/repo>` | inferred | Build the GitHub template from this. |
-| `--name <str>` | `<repo> wiki` | `site.name`. |
+| Flag                   | Default                    | Meaning                                     |
+| ---------------------- | -------------------------- | ------------------------------------------- |
+| `--wiki <dir>`         | `./wiki`                   | Markdown source directory.                  |
+| `--out <path>`         | `<wiki>/search-index.json` | Where to write.                             |
+| `--stdout`             | —                          | Print the index instead of writing a file.  |
+| `--url-template <tpl>` | inferred                   | Result-URL template; must contain `{page}`. |
+| `--repo <owner/repo>`  | inferred                   | Build the GitHub template from this.        |
+| `--name <str>`         | `<repo> wiki`              | `site.name`.                                |
 
 What it does: one section per ATX heading (plus a page-top preamble section),
 GitHub-style heading anchors with `-1`/`-2` disambiguation, `#`-in-code-fence

package/builder/lib/build-index.mjs

@@ -5,10 +5,10 @@
 // order, sequential ids, no timestamps — so a CI `git diff --exit-code` can gate
 // a stale committed index.
 
-import { readdir, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { splitSections } from './markdown.mjs';
-import { createSlugger } from './slug.mjs';
+import {readdir, readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {splitSections} from './markdown.mjs';
+import {createSlugger} from './slug.mjs';
 
 // GitHub stores page "Foo Bar" as Foo-Bar.md and special pages (_Sidebar,
 // _Footer, …) start with an underscore — those are chrome, not content.
@@ -19,7 +19,7 @@ const firstH1 = md => {
   return m ? m[1].trim() : null;
 };
 
-export const buildIndex = async ({ wikiDir, urlTemplate, siteName, fragments = true }) => {
+export const buildIndex = async ({wikiDir, urlTemplate, siteName, fragments = true}) => {
   const files = (await readdir(wikiDir)).filter(isContentPage).sort();
   const docs = [];
   let id = 0;
@@ -36,10 +36,10 @@ export const buildIndex = async ({ wikiDir, urlTemplate, siteName, fragments = t
         title,
         heading: sec.heading ?? title,
         anchor: sec.heading ? slug(sec.heading) : '', // preamble → page top (no anchor)
-        text: sec.text || sec.heading || title,
+        text: sec.text || sec.heading || title
       });
     }
   }
 
-  return { v: 1, site: { name: siteName, urlTemplate, fragments }, docs };
+  return {v: 1, site: {name: siteName, urlTemplate, fragments}, docs};
 };

package/builder/lib/markdown.mjs

@@ -9,34 +9,94 @@ const ATX = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
 // preamble section with heading=null, level=0. `#` inside fenced code is
 // ignored so code comments don't masquerade as headings.
 export const splitSections = md => {
-  const sections = [{ level: 0, heading: null, lines: [] }];
+  const sections = [{level: 0, heading: null, lines: []}];
   let inFence = false;
   for (const line of md.split(/\r?\n/)) {
     if (FENCE.test(line)) inFence = !inFence;
     const m = inFence ? null : ATX.exec(line);
-    if (m) sections.push({ level: m[1].length, heading: m[2].trim(), lines: [] });
+    if (m) sections.push({level: m[1].length, heading: m[2].trim(), lines: []});
     else sections.at(-1).lines.push(line);
   }
   return sections
-    .map(s => ({ level: s.level, heading: s.heading, text: toPlainText(s.lines.join('\n')) }))
+    .map(s => ({level: s.level, heading: s.heading, text: toPlainText(s.lines.join('\n'))}))
     .filter(s => s.heading || s.text); // drop an empty preamble
 };
 
+// Common named HTML entities found in wiki prose — typographic punctuation and
+// symbols. Each maps to its character so it drops out at tokenization (— is
+// punctuation, not a word) instead of surviving as a junk term ("mdash"), and so
+// snippets render the glyph rather than the literal "—".
+const NAMED_ENTITIES = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  mdash: '—',
+  ndash: '–',
+  hellip: '…',
+  bull: '•',
+  middot: '·',
+  copy: '©',
+  reg: '®',
+  trade: '™',
+  sect: '§',
+  para: '¶',
+  deg: '°',
+  plusmn: '±',
+  times: '×',
+  divide: '÷',
+  minus: '−',
+  frasl: '⁄',
+  laquo: '«',
+  raquo: '»',
+  lsquo: '‘',
+  rsquo: '’',
+  ldquo: '“',
+  rdquo: '”',
+  larr: '←',
+  rarr: '→',
+  uarr: '↑',
+  darr: '↓',
+  harr: '↔',
+  le: '≤',
+  ge: '≥',
+  ne: '≠',
+  prime: '′',
+  Prime: '″'
+};
+
+// Resolve HTML entities so they never pollute the term index. Numeric entities
+// (&#1234; / &#x1F50D;) decode generally — preserving genuine letters that happen
+// to be encoded (&#945; → α) while the typographic noise (&mdash;, arrows, emoji)
+// decodes to punctuation/symbols the tokenizer discards. Known named entities map
+// via the table above; anything else unknown collapses to a space so it can't
+// become a junk term ("mdash", "128269").
+const ENTITY_RE = /&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z][a-zA-Z0-9]*);/g;
+const decodeEntity = (_m, body) => {
+  if (body[0] !== '#') return NAMED_ENTITIES[body] ?? ' ';
+  const cp =
+    body[1] === 'x' || body[1] === 'X' ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+  return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : ' ';
+};
+
 // Reduce Markdown to plain, collapsed text. Code *text* is kept (API names are
 // worth searching) — only the fence delimiters are removed.
 export const toPlainText = md =>
   md
     .replace(/^[ \t]*(```|~~~).*$/gm, ' ') // fence delimiters (keep the code text)
-    .replace(/`([^`]*)`/g, '$1')           // inline code → its text
+    .replace(/`([^`]*)`/g, '$1') // inline code → its text
     .replace(/\[\[([^\]|]+)\|([^\]]+)\]\]/g, '$1') // [[Display|Page]] wiki link → Display
-    .replace(/\[\[([^\]]+)\]\]/g, '$1')    // [[Page]] wiki link → Page
+    .replace(/\[\[([^\]]+)\]\]/g, '$1') // [[Page]] wiki link → Page
     .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1') // image → alt
-    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')  // link → text
-    .replace(/<[^>]+>/g, ' ')              // strip HTML tags
-    .replace(/^[ \t>]*>+/gm, ' ')          // blockquote markers
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // link → text
+    .replace(/<[^>]+>/g, ' ') // strip HTML tags
+    .replace(ENTITY_RE, decodeEntity) // HTML entities → glyph (drops &mdash;/&#1234; noise)
+    .replace(/^[ \t>]*>+/gm, ' ') // blockquote markers
     .replace(/^\s{0,3}([-*+]|\d+\.)\s+/gm, ' ') // list markers
-    .replace(/[*_~]+/g, '')                // emphasis
+    .replace(/[*_~]+/g, '') // emphasis
     .replace(/^\s*\|.*$/gm, m => m.replace(/\|/g, ' ')) // table pipes
-    .replace(/^#{1,6}\s+/gm, '')           // stray heading marks
+    .replace(/^#{1,6}\s+/gm, '') // stray heading marks
     .replace(/\s+/g, ' ')
     .trim();

package/builder/lib/slug.mjs

@@ -2,17 +2,17 @@
 //
 // GitHub lowercases a heading, strips most punctuation, turns spaces into
 // hyphens, and disambiguates repeats *within a page* as -1, -2, …. This is a
-// close approximation, good enough for English docs; S2/S3 verify the anchors
-// against real rendered pages and flag any divergence.
+// close approximation, good enough for English docs; verified against real
+// rendered GitHub wiki pages.
 
 export const slugify = text =>
   text
     .trim()
     .toLowerCase()
-    .replace(/\s+/g, ' ')                // collapse source whitespace, as HTML rendering does
-    .replace(/[^\p{L}\p{N}_ -]+/gu, '')  // drop punctuation/symbols (em dash, quotes, colon, parens…)
-    .replace(/ /g, '-');                 // each remaining space → one hyphen, so a removed char
-                                         // between two spaces yields "--", matching github-slugger
+    .replace(/\s+/g, ' ') // collapse source whitespace, as HTML rendering does
+    .replace(/[^\p{L}\p{N}_ -]+/gu, '') // drop punctuation/symbols (em dash, quotes, colon, parens…)
+    .replace(/ /g, '-'); // each remaining space → one hyphen, so a removed char
+// between two spaces yields "--", matching github-slugger
 
 // A per-page deduping slugger: call the returned fn on each heading in document
 // order so duplicates get GitHub's -1 / -2 / … suffixes.

package/builder/wiki-index.mjs

@@ -9,11 +9,11 @@
 // dir's git origin (…/<owner>/<repo>.wiki.git) and builds the GitHub template.
 // Default --out is <wiki>/search-index.json (the index is hosted from the wiki).
 
-import { writeFile } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { buildIndex } from './lib/build-index.mjs';
+import {writeFile} from 'node:fs/promises';
+import {join, resolve} from 'node:path';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {buildIndex} from './lib/build-index.mjs';
 
 const run = promisify(execFile);
 
@@ -27,9 +27,13 @@ const parseArgs = argv => {
     const m = /^--([^=]+)(?:=(.*))?$/.exec(argv[i]);
     if (!m) continue;
     const key = m[1];
-    if (m[2] !== undefined) { args[key] = m[2]; continue; }
+    if (m[2] !== undefined) {
+      args[key] = m[2];
+      continue;
+    }
     const next = argv[i + 1];
-    if (!BOOLEAN_FLAGS.has(key) && next !== undefined && !next.startsWith('--')) args[key] = argv[++i];
+    if (!BOOLEAN_FLAGS.has(key) && next !== undefined && !next.startsWith('--'))
+      args[key] = argv[++i];
     else args[key] = true;
   }
   return args;
@@ -38,7 +42,7 @@ const parseArgs = argv => {
 // owner/repo from the wiki clone's origin, tolerating the …/.wiki.git suffix.
 const inferRepo = async wikiDir => {
   try {
-    const { stdout } = await run('git', ['-C', wikiDir, 'remote', 'get-url', 'origin']);
+    const {stdout} = await run('git', ['-C', wikiDir, 'remote', 'get-url', 'origin']);
     const m = /[/:]([^/]+)\/([^/]+?)(?:\.wiki)?\.git$/.exec(stdout.trim());
     return m ? `${m[1]}/${m[2]}` : null;
   } catch {
@@ -55,15 +59,20 @@ const main = async () => {
 
   const urlTemplate = args['url-template'] || (repo && `https://github.com/${repo}/wiki/{page}`);
   if (!urlTemplate) {
-    console.error('wiki-index: need --url-template or --repo owner/repo (could not infer from git origin).');
+    console.error(
+      'wiki-index: need --url-template or --repo owner/repo (could not infer from git origin).'
+    );
     process.exit(2);
   }
   const siteName = args.name || (repo ? `${repo.split('/')[1]} wiki` : 'wiki');
 
-  const index = await buildIndex({ wikiDir, urlTemplate, siteName });
+  const index = await buildIndex({wikiDir, urlTemplate, siteName});
   const json = JSON.stringify(index, null, 2) + '\n';
 
-  if (args.stdout) { process.stdout.write(json); return; }
+  if (args.stdout) {
+    process.stdout.write(json);
+    return;
+  }
 
   const out = resolve(args.out || join(wikiDir, 'search-index.json'));
   await writeFile(out, json);

package/llms-full.txt

@@ -0,0 +1,156 @@
+# wiki-search — full LLM reference
+
+`wiki-search` adds real search to a GitHub wiki (or any Markdown docs site) and jumps the reader to the matching section, without moving the docs. It has two parts:
+
+1. **`wiki-search-index`** — the npm CLI (this package) that compiles Markdown into a self-describing JSON search index.
+2. **The hosted search app** — a static GitHub Pages site that loads an index, searches it, and deep-links each hit via Text Fragments. A thin bookmarklet opens it on any wiki page.
+
+Zero runtime dependencies. No build step — the CLI is `.mjs`, the app is browser ESM.
+
+---
+
+## 1. The CLI — `wiki-search-index`
+
+`bin`: `wiki-search-index` → `builder/wiki-index.mjs`.
+
+```
+wiki-search-index [options]
+```
+
+### Options
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--wiki <dir>` | `./wiki` | Markdown source directory. |
+| `--out <path>` | `<wiki>/search-index.json` | Output file. |
+| `--repo <owner/repo>` | — | GitHub repo; builds the wiki URL template `https://github.com/<owner>/<repo>/wiki/{page}`. |
+| `--url-template <tpl>` | — | Result-URL template; **must contain `{page}`**. For any non-GitHub site. |
+| `--name <site name>` | `<repo> wiki` or `wiki` | Human label shown in the search UI. |
+| `--stdout` | off | Write the index to stdout instead of a file. |
+
+Flags accept both `--key value` and `--key=value`. `--stdout` is a valueless boolean.
+
+### Repo inference
+
+With neither `--url-template` nor `--repo`, the tool reads the wiki dir's git origin (`git -C <wiki> remote get-url origin`) and extracts `owner/repo`, tolerating the `…/<owner>/<repo>.wiki.git` suffix. If it can't determine a URL template (no `--url-template`, no `--repo`, and inference fails), it prints an error and exits `2`.
+
+### Output
+
+On success it writes pretty-printed JSON (2-space indent, trailing newline) and logs to **stderr** a one-line summary: `wiki-index: <N> sections from <P> page(s) → <out>` plus the site name and URL template. With `--stdout` the JSON goes to stdout and nothing else is written.
+
+### Examples
+
+```bash
+# GitHub wiki — owner/repo inferred from the wiki's git origin
+npx wiki-search-index --wiki ./wiki
+
+# Explicit repo (origin lacks the .wiki.git suffix, e.g. an SSH submodule)
+npx wiki-search-index --wiki ./wiki --repo uhop/stream-json
+
+# Non-GitHub docs site
+npx wiki-search-index --wiki ./docs --url-template 'https://example.com/docs/{page}' --name 'Example docs'
+
+# Emit to stdout
+npx wiki-search-index --wiki ./wiki --stdout > index.json
+```
+
+---
+
+## 2. Index format (v1)
+
+A wiki-search index is a single self-describing JSON document (canonical spec: `INDEX-FORMAT.md`). A client assumes nothing beyond this contract.
+
+```json
+{
+  "v": 1,
+  "site": {
+    "name": "wiki-search wiki",
+    "urlTemplate": "https://github.com/uhop/wiki-search/wiki/{page}",
+    "fragments": true
+  },
+  "docs": [
+    {
+      "id": 0,
+      "page": "Index-Format",
+      "title": "Index format",
+      "heading": "Validation",
+      "anchor": "validation",
+      "text": "full plain text of the section…"
+    }
+  ]
+}
+```
+
+### Fields
+
+- `v` — format version (`1`). Clients reject a version they don't understand.
+- `site.name` — human label for the corpus.
+- `site.urlTemplate` — result-URL template; **must contain `{page}`**. No hardcoded host.
+- `site.fragments` — `true` if the target renders Text Fragments; when `false`, clients omit the `:~:text=` directive.
+- `docs[]` — one entry per indexed section.
+- `doc.id` — stable integer, sequential in build order.
+- `doc.page` — the `{page}` substitution (for GitHub wikis, the page's URL segment, e.g. `Foo-Bar`).
+- `doc.title` — page display title.
+- `doc.heading` — section heading (falls back to the page title for a page's preamble).
+- `doc.anchor` — in-page anchor slug; `""` means the page top.
+- `doc.text` — plain-text body of the section (Markdown stripped), for the search engine.
+
+### Building a result URL
+
+```
+base = urlTemplate.replace("{page}", encodeURIComponent(doc.page))
+hash = doc.anchor || ""                       (omit if empty)
+text = ":~:text=" + <matched phrase>          (only if site.fragments and a phrase)
+result = base + ("#" + hash + text)           (only if hash or text)
+```
+
+### Validation (verify-or-explain)
+
+A client must check, and on any failure show a specific message (never a blank box): (1) the index is fetchable; (2) it is valid JSON; (3) `v` is supported; (4) `site.urlTemplate` is present and contains `{page}`; (5) `docs` is a non-empty array, each entry having `page`, `title`, `text`.
+
+### Versioning
+
+`v` increases only on a breaking change. Additive optional fields do not bump `v`; clients ignore unknown fields. A client meeting a higher `v` than it knows stops and says so.
+
+---
+
+## 3. The hosted app
+
+Static site at `https://uhop.github.io/wiki-search/app/`. It loads an index, searches, and renders hits as real `<a>` links with `#anchor:~:text=phrase` directives. Query parameters (priority order):
+
+- `?index=<url>` — load any v1 index from any URL.
+- `?wiki=<owner>/<repo>` — convenience: derive `https://raw.githubusercontent.com/wiki/<owner>/<repo>/search-index.json` (override the file with `?file=<name>`).
+- `?from=<page url>` — the current page URL, passed by the bookmarklet; the app parses `owner/repo` from it (any `github.com/<owner>/<repo>` page — repo root, `/wiki/…`, `/actions`, etc.).
+- `?q=<query>` — pre-fill the search box.
+- `?target=opener|new|tab`, `?anchor=off`, `?text=off` — positioning levers (also in the Options row).
+
+With none of `?index` / `?wiki` / `?from` resolvable, the app explains ("nothing to search yet") rather than showing a blank box.
+
+### The bookmarklet
+
+`bookmarklet/bookmarklet.js` exports `APP_URL` and `BOOKMARKLET`. The bookmarklet is a thin launcher — `window.open(APP_URL + '?from=' + encodeURIComponent(location.href), …)` — so it opens the app on its own origin (bypassing the wiki page's CSP) and lets the app do owner/repo detection. Only `APP_URL` is frozen into a saved bookmark; everything else is server-side and updates on redeploy.
+
+---
+
+## 4. Adoption recipe
+
+```bash
+# 1. Build the index from your wiki's Markdown
+npx wiki-search-index --wiki ./wiki              # (--repo owner/repo if the origin lacks .wiki.git)
+# 2. Commit ./wiki/search-index.json into the wiki repo
+# 3. Link the hosted app from the wiki (Home / sidebar):
+#    https://uhop.github.io/wiki-search/app/?wiki=<owner>/<repo>
+#    plus the one-click bookmarklet from https://uhop.github.io/wiki-search/
+```
+
+Rebuild the index whenever the wiki's Markdown changes (the output is deterministic, so a CI `git diff --exit-code` can gate staleness).
+
+---
+
+## Links
+
+- Demo + install: https://uhop.github.io/wiki-search/
+- Wiki: https://github.com/uhop/wiki-search/wiki
+- Source: https://github.com/uhop/wiki-search
+- npm: https://www.npmjs.com/package/wiki-search-index
+- Index format: https://github.com/uhop/wiki-search/blob/main/INDEX-FORMAT.md

package/llms.txt

@@ -0,0 +1,73 @@
+# wiki-search-index
+
+> CLI that builds a self-describing search index from a GitHub wiki (or any Markdown docs). It's the indexer for `wiki-search` — a bookmarklet + hosted app that search a wiki and jump to the matching section. Zero dependencies, no build step.
+
+## Install
+
+```bash
+npx wiki-search-index --wiki ./wiki   # no install needed
+# or, as a dev dependency:
+npm i -D wiki-search-index
+```
+
+## Quick start
+
+```bash
+# Build an index for a GitHub wiki checked out at ./wiki
+npx wiki-search-index --wiki ./wiki
+# → ./wiki/search-index.json
+```
+
+Commit `search-index.json` into the wiki (it's served from `raw.githubusercontent.com`), then point the hosted app at it: `https://uhop.github.io/wiki-search/app/?wiki=<owner>/<repo>`.
+
+## CLI
+
+`wiki-search-index [options]`
+
+- `--wiki <dir>` — Markdown source directory (default `./wiki`).
+- `--out <path>` — output file (default `<wiki>/search-index.json`).
+- `--repo <owner/repo>` — GitHub repo; builds the wiki URL template. Needed when the wiki's git origin lacks the `.wiki.git` suffix the tool infers from.
+- `--url-template <tpl>` — result-URL template containing `{page}` (for any non-GitHub site).
+- `--name <site name>` — human label shown in the search UI.
+- `--stdout` — write the index to stdout instead of a file.
+
+With neither `--url-template` nor `--repo`, owner/repo is inferred from the wiki dir's git origin (`…/<owner>/<repo>.wiki.git`). Exit code `2` if neither is given and inference fails.
+
+## Output — index format v1
+
+A single self-describing JSON document (full spec: INDEX-FORMAT.md):
+
+```json
+{
+  "v": 1,
+  "site": { "name": "...", "urlTemplate": "https://github.com/<o>/<r>/wiki/{page}", "fragments": true },
+  "docs": [
+    { "id": 0, "page": "Page-Name", "title": "Page title", "heading": "Section", "anchor": "section", "text": "plain text…" }
+  ]
+}
+```
+
+A client validates `v` + required fields, then builds each result URL from `site.urlTemplate` alone — no hardcoded host, so any site emitting this shape is searchable. The output is deterministic (sorted, no timestamps), so a CI `git diff --exit-code` can gate index staleness.
+
+## Common patterns
+
+```bash
+# Explicit repo (origin lacks the .wiki.git suffix)
+npx wiki-search-index --wiki ./wiki --repo uhop/stream-json
+
+# Non-GitHub docs site
+npx wiki-search-index --wiki ./docs --url-template 'https://example.com/docs/{page}' --name 'Example docs'
+
+# Pipe the index elsewhere
+npx wiki-search-index --wiki ./wiki --stdout > index.json
+```
+
+Rebuild whenever the wiki's Markdown changes — an index does not go stale on its own.
+
+## Links
+
+- Demo + install: https://uhop.github.io/wiki-search/
+- Wiki: https://github.com/uhop/wiki-search/wiki
+- npm: https://www.npmjs.com/package/wiki-search-index
+- Index format: https://github.com/uhop/wiki-search/blob/main/INDEX-FORMAT.md
+- Full LLM reference: https://github.com/uhop/wiki-search/blob/main/llms-full.txt

package/package.json

@@ -1,19 +1,29 @@
 {
   "name": "wiki-search-index",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Build a self-describing search index from a GitHub wiki (or any Markdown docs) — the indexer for wiki-search.",
   "type": "module",
   "bin": {
     "wiki-search-index": "builder/wiki-index.mjs"
   },
+  "scripts": {
+    "test": "node builder/test/run.mjs",
+    "lint": "prettier --check .",
+    "lint:fix": "prettier --write ."
+  },
   "files": [
     "builder/wiki-index.mjs",
     "builder/lib",
     "builder/README.md",
-    "INDEX-FORMAT.md"
+    "INDEX-FORMAT.md",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "prettier": "^3.8.3"
   },
   "keywords": [
     "wiki",
@@ -26,6 +36,8 @@
     "static-search"
   ],
   "homepage": "https://uhop.github.io/wiki-search/",
+  "llms": "https://raw.githubusercontent.com/uhop/wiki-search/main/llms.txt",
+  "llmsFull": "https://raw.githubusercontent.com/uhop/wiki-search/main/llms-full.txt",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/uhop/wiki-search.git"
@@ -34,5 +46,9 @@
     "url": "https://github.com/uhop/wiki-search/issues"
   },
   "author": "Eugene Lazutkin",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/uhop"
+  },
   "license": "BSD-3-Clause"
 }