@docubook/plugin-search-algolia

Algolia DocSearch v5 for DocuBook Flame.

• Search opens the DocSearch dialog with keyword results only, from Flame's sidebar search bar, the mobile search icon, or ⌘ K / Ctrl K.
• Ask AI (optional) opens the DocSearch side panel, a separate surface, from a Sparkles button beside the sidebar search bar, an Ask AI row in the mobile menu drawer, or ⌘ I / Ctrl I.

The dialog and panel use your Flame theme colors and follow the light/dark toggle. DocSearch is served from your own domain and downloaded only when a reader first reaches for search.

Install

npm install -D @docubook/plugin-search-algolia

{
  "plugins": [
    ["@docubook/plugin-search-algolia", {
      "appId": "YOUR_APP_ID",
      "apiKey": "YOUR_SEARCH_ONLY_API_KEY",
      "indexName": "YOUR_INDEX_NAME",
      "askAi": "YOUR_AGENT_ID"
    }]
  ]
}

Leave out askAi for search only. Use a search-only API key, never the Admin key.

Options

| Option | Type | Description | | --- | --- | --- | | appId | string | Required. Algolia application ID. | | apiKey | string | Required. Search-only API key. | | indexName | string | Required. Index the crawler writes to. | | askAi | string | object | Agent Studio agent ID, or { agentId, appId?, apiKey?, indices?, searchParameters?, suggestedQuestions?, variant?, side?, width?, expandedWidth?, translations? }. | | searchParameters | object | Algolia search parameters for the dialog. | | placeholder | string | Search input placeholder. | | maxResultsPerGroup | number | Maximum results per group. | | disableUserPersonalization | boolean | Do not store recent and favorite searches. | | translations | object | DocSearch modal translations. | | relativeUrls | boolean | Default true: open results on the current origin rather than the crawled one. |

Full guide, including the crawler configuration: Algolia search.

How it works

The plugin declares a search provider on docs pages (see Search providers) and copies its browser build into Flame's bundle directory (assets/docsearch/). Flame keeps rendering the search bar and buttons and imports docsearch/client.js on first use. That module mounts @docsearch/js/docsearch (the keyword-only entry) and @docsearch/sidepanel-js, each loaded when first opened, with DocSearch's own buttons and shortcuts turned off.

Requires @docubook/flame with search provider support (DevServerContext.assetsPath).

On Flame versions with split-workspace support, Ask AI docks in its own box beside the documentation at desktop widths (1024px and above). The document keeps its own box and scroll position, and its TOC becomes evenly spaced dots with heading titles on hover or keyboard focus. Each dot navigates to a section, and the active section is highlighted. Use the panel's expand/collapse button to adjust its width; the document automatically shares the available space. On narrower screens Ask AI fills the viewport. Closing it restores the document and full TOC. The variant option remains a fallback for hosts without this layout support.

On narrow desktops, the compact rail's navigation button explicitly closes Ask AI and reveals the full sidebar, moving focus into the visible navigation. On mobile, opening Flame's navigation drawer dismisses search and Ask AI. Opening search or Ask AI while navigation is open returns to that surface, so only one overlay stays active.

Development

pnpm --filter @docubook/plugin-search-algolia build   # dist/index.js + dist/client/
pnpm --filter @docubook/plugin-search-algolia test