Search index

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.

npx @doc-kit/cli generate -t html -t orama-db -i "docs/**/*.md" -o out

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 the global options. Keep its output the site's output directory, since the search box loads the index from the site root.

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

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.

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"
  }
]

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.

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' });

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).