On this page

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.

Target: orama-db · Package: @doc-kit/generator-react · Reads: API entries · Writes: orama-db.json

npm install --save-dev @doc-kit/cli @doc-kit/generator-react
npx doc-kit generate -t html -t orama-db -i "docs/**/*.md" -o out
Shell

Building both in one run adds a search box to the site's navigation bar, which Ctrl+K or Cmd+K also opens.

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:

export default {
  'orama-db': {
    minify: true,
  },
};
JavaScript
Attributes
output?:string
The directory to write orama-db.json to. Keep it the site's output directory, since the search box loads the index from the site root. Without one, nothing is written. Default: from global.output (--output).
minify?:boolean
Write the index on a single line instead of indented. Its nested JSON is mostly indentation, so this makes it about three times smaller, and still noticeably smaller once your host compresses it. Default: false, from global.minify (--minify).

The index holds one document per heading on every page, that is, one per API entry. Each document has four string fields:

FieldWhat it holds
titleThe 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.
descriptionThe first paragraph under the heading, with inline code kept in backticks. Left out when the section has no paragraph.
hrefThe page's path from the site root, with .html and the heading's anchor.
siteSectionThe page's title (its first heading). Search results are grouped by it.

For example, this page:

# Kittens

Everything about `Kitten` objects.

## Class: `Kitten`

A small cat.

### `kitten.meow([volume])`

- `volume` {number} How loud. **Default:** `1`.

Makes the kitten meow.

## Care

- Feed twice a day.
Markdown

becomes these four documents, which orama-db.json stores along with Orama's search indexes:

[
  {
    "title": "Kittens",
    "description": "Everything about `Kitten` objects.",
    "href": "/kittens.html#kittens",
    "siteSection": "Kittens"
  },
  {
    "title": "Kitten",
    "description": "A small cat.",
    "href": "/kittens.html#class-kitten",
    "siteSection": "Kittens"
  },
  {
    "title": "Kitten > meow",
    "description": "Makes the kitten meow.",
    "href": "/kittens.html#kittenmeowvolume",
    "siteSection": "Kittens"
  },
  {
    "title": "Care",
    "href": "/kittens.html#care",
    "siteSection": "Kittens"
  }
]
JSON

The meow description skips the parameter list and takes the paragraph after it, and Care has no description because its section holds only a list.

  • The search box shows when orama-db and html run together, since that's when the website's showSearchBox option defaults to true. If you build the index in another run, set showSearchBox: true under html.
  • The index loads on the first search, not with the page, and stays loaded as the reader moves between pages. Browsers don't let a page opened from disk fetch it, so serve the site over HTTP, with npx doc-kit preview locally. When it can't be loaded, for example because orama-db.json isn't at the site root, searches come back empty, and the next search tries again.
  • It's fetched from the site root, relative to the current page, so a site published under a path (https://example.com/docs/) finds it too. With html's useAbsoluteURLs on, it's fetched from baseURL instead. Result links resolve the same way.
  • Results come up to 10 at a time as you type, grouped under their page's title. Tabs for the pages with the most matches (up to 10) narrow them to one page and show up to 25. Each result links to its heading on the full page, even when you also build section pages.

Publishing your docs covers hosting, compression and caching.

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:

import { create, load, search } from '@orama/orama';

const db = create({ schema: {} });
const data = await fetch('/orama-db.json').then(response => response.json());

load(db, data);

const { hits } = await search(db, { term: 'meow' });
JavaScript

Each hit's document has the fields above; resolve its href against your site's root. A generator of your own that names '@doc-kit/generator-react/orama-db' in its dependsOn receives the same saved database (see Creating generators).

PreviousSection pagesNextSitemap