{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-orama-db","path":"/generators/orama-db","type":"module","module":"generators-orama-db","title":"Search index","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `orama-db` generator builds the search index behind the\n[website](https://doc-kit.nodejs.org/generators/html)'s search box: an\n[Orama](https://github.com/oramasearch/orama) database with one document per\nheading in your docs. Build it alongside `html` whenever your site should have\nsearch.\n\n**Target:** `orama-db` · **Package:** [`@doc-kit/generator-react`](https://doc-kit.nodejs.org/packages/react) · **Reads:** [API entries](https://doc-kit.nodejs.org/generators/metadata) · **Writes:** `orama-db.json`","summary":"The `orama-db` generator builds the search index behind the website's search box: an Orama database with one document per heading in your docs. Build it alongside `html` whenever your site should have search.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpm install --save-dev @doc-kit/cli @doc-kit/generator-react\nnpx doc-kit generate -t html -t orama-db -i \"docs/**/*.md\" -o out\n```\n\nBuilding both in one run adds a search box to the site's navigation bar, which\nCtrl+K or Cmd+K also opens.","summary":"Building both in one run adds a search box to the site's navigation bar, which Ctrl+K or Cmd+K also opens.","examples":[{"language":"bash","displayName":null,"code":"npm install --save-dev @doc-kit/cli @doc-kit/generator-react\nnpx doc-kit generate -t html -t orama-db -i \"docs/**/*.md\" -o out"}],"children":[]},{"kind":"section","id":"configuring","name":"Configuring","title":"Configuring","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`orama-db` has no options of its own. It reads these global options, which you\ncan also set in an `orama-db` section to apply to it alone:\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n  'orama-db': {\n    minify: true,\n  },\n};\n```\n\n* `output` {string} The directory to write `orama-db.json` to. Keep it the\n  site's output directory, since the search box loads the index from the site\n  root. Without one, nothing is written. **Default:** from `global.output`\n  (`--output`).\n* `minify` {boolean} Write the index on a single line instead of indented. Its\n  nested JSON is mostly indentation, so this makes it about three times\n  smaller, and still noticeably smaller once your host compresses it.\n  **Default:** `false`, from `global.minify` (`--minify`).","summary":"`orama-db` has no options of its own. It reads these global options, which you can also set in an `orama-db` section to apply to it alone:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n  'orama-db': {\n    minify: true,\n  },\n};"}],"children":[]},{"kind":"section","id":"what-gets-indexed","name":"What gets indexed","title":"What gets indexed","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The index holds one document per heading on every page, that is, one per\n[API entry](https://doc-kit.nodejs.org/generators/metadata). Each document has\nfour string fields:\n\n| Field         | What it holds                                                                                                                                                                                                                                                                          |\n| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `title`       | The heading's name, prefixed with the names of the headings it sits under (except the page title) and joined with `>`, as in `Kitten > meow`. An API heading contributes only the API's name (`meow` for `kitten.meow([volume])`); other headings keep their inline code in backticks. |\n| `description` | The first paragraph under the heading, with inline code kept in backticks. Left out when the section has no paragraph.                                                                                                                                                                 |\n| `href`        | The page's path from the site root, with `.html` and the heading's anchor.                                                                                                                                                                                                             |\n| `siteSection` | The page's title (its first heading). Search results are grouped by it.                                                                                                                                                                                                                |\n\nFor example, this page:\n\n```md displayName=\"docs/kittens.md\"\n# Kittens\n\nEverything about `Kitten` objects.\n\n## Class: `Kitten`\n\nA small cat.\n\n### `kitten.meow([volume])`\n\n- `volume` {number} How loud. **Default:** `1`.\n\nMakes the kitten meow.\n\n## Care\n\n- Feed twice a day.\n```\n\nbecomes these four documents, which `orama-db.json` stores along with Orama's\nsearch indexes:\n\n```json\n[\n  {\n    \"title\": \"Kittens\",\n    \"description\": \"Everything about `Kitten` objects.\",\n    \"href\": \"/kittens.html#kittens\",\n    \"siteSection\": \"Kittens\"\n  },\n  {\n    \"title\": \"Kitten\",\n    \"description\": \"A small cat.\",\n    \"href\": \"/kittens.html#class-kitten\",\n    \"siteSection\": \"Kittens\"\n  },\n  {\n    \"title\": \"Kitten > meow\",\n    \"description\": \"Makes the kitten meow.\",\n    \"href\": \"/kittens.html#kittenmeowvolume\",\n    \"siteSection\": \"Kittens\"\n  },\n  {\n    \"title\": \"Care\",\n    \"href\": \"/kittens.html#care\",\n    \"siteSection\": \"Kittens\"\n  }\n]\n```\n\nThe `meow` description skips the parameter list and takes the paragraph after\nit, and `Care` has no description because its section holds only a list.","summary":"The index holds one document per heading on every page, that is, one per API entry. Each document has four string fields:","examples":[{"language":"md","displayName":"docs/kittens.md","code":"# Kittens\n\nEverything about `Kitten` objects.\n\n## Class: `Kitten`\n\nA small cat.\n\n### `kitten.meow([volume])`\n\n- `volume` {number} How loud. **Default:** `1`.\n\nMakes the kitten meow.\n\n## Care\n\n- Feed twice a day."},{"language":"json","displayName":null,"code":"[\n  {\n    \"title\": \"Kittens\",\n    \"description\": \"Everything about `Kitten` objects.\",\n    \"href\": \"/kittens.html#kittens\",\n    \"siteSection\": \"Kittens\"\n  },\n  {\n    \"title\": \"Kitten\",\n    \"description\": \"A small cat.\",\n    \"href\": \"/kittens.html#class-kitten\",\n    \"siteSection\": \"Kittens\"\n  },\n  {\n    \"title\": \"Kitten > meow\",\n    \"description\": \"Makes the kitten meow.\",\n    \"href\": \"/kittens.html#kittenmeowvolume\",\n    \"siteSection\": \"Kittens\"\n  },\n  {\n    \"title\": \"Care\",\n    \"href\": \"/kittens.html#care\",\n    \"siteSection\": \"Kittens\"\n  }\n]"}],"children":[]},{"kind":"section","id":"how-the-site-uses-it","name":"How the site uses it","title":"How the site uses it","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* **The search box shows** when `orama-db` and `html` run together, since\n  that's when the website's\n  [`showSearchBox`](https://doc-kit.nodejs.org/generators/html#configuring)\n  option defaults to `true`. If you build the index in another run, set\n  `showSearchBox: true` under `html`.\n* **The index loads on the first search**, not with the page, and stays loaded\n  as the reader moves between pages. Browsers don't let a page opened from\n  disk fetch it, so serve the site over HTTP, with `npx doc-kit preview`\n  locally. When it can't be loaded, for example because `orama-db.json` isn't\n  at the site root, searches come back empty, and the next search tries again.\n* **It's fetched from the site root**, relative to the current page, so a site\n  published under a path (`https://example.com/docs/`) finds it too. With\n  `html`'s `useAbsoluteURLs` on, it's fetched from `baseURL` instead. Result\n  links resolve the same way.\n* **Results** come up to 10 at a time as you type, grouped under their page's\n  title. Tabs for the pages with the most matches (up to 10) narrow them to one\n  page and show up to 25. Each result links to its heading on the full page,\n  even when you also build\n  [section pages](https://doc-kit.nodejs.org/generators/section-pages).\n\n[Publishing your docs](https://doc-kit.nodejs.org/publishing) covers hosting,\ncompression and caching.","summary":"Publishing your docs covers hosting, compression and caching.","examples":[],"children":[]},{"kind":"section","id":"querying-it-yourself","name":"Querying it yourself","title":"Querying it yourself","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`orama-db.json` is an Orama database saved with Orama's `save()`, so you can\nload it with [`@orama/orama`](https://www.npmjs.com/package/@orama/orama) to\nbuild a search of your own in the browser:\n\n```js displayName=\"search.mjs\"\nimport { create, load, search } from '@orama/orama';\n\nconst db = create({ schema: {} });\nconst data = await fetch('/orama-db.json').then(response => response.json());\n\nload(db, data);\n\nconst { hits } = await search(db, { term: 'meow' });\n```\n\nEach hit's `document` has the fields above; resolve its `href` against your\nsite's root. A generator of your own that names\n`'@doc-kit/generator-react/orama-db'` in its `dependsOn` receives the same\nsaved database (see\n[Creating generators](https://doc-kit.nodejs.org/creating-generators)).","summary":"`orama-db.json` is an Orama database saved with Orama's `save()`, so you can load it with `@orama/orama` to build a search of your own in the browser:","examples":[{"language":"js","displayName":"search.mjs","code":"import { create, load, search } from '@orama/orama';\n\nconst db = create({ schema: {} });\nconst data = await fetch('/orama-db.json').then(response => response.json());\n\nload(db, data);\n\nconst { hits } = await search(db, { term: 'meow' });"}],"children":[]}]}