Skip to main content
Version: Stable (v4.x)

Docusaurus Adapter (Recommended)

If you use Docusaurus, install and configure @docsearch/docusaurus-adapter to get the latest DocSearch features on your current Docusaurus version.

Why this adapter exists​

Docusaurus ships an excellent built-in Algolia integration (@docusaurus/theme-search-algolia), but Docusaurus (Meta-maintained) and DocSearch don't always release on the same cadence.

The DocSearch adapter lets us ship new DocSearch features (including Ask AI sidepanel support) without forcing users to wait for a Docusaurus integration update.

In practice, this means:

  • Faster access to new DocSearch capabilities.
  • Better compatibility for Ask AI + sidepanel features.
  • A dedicated search integration path maintained in the DocSearch project.

Install​

yarn add @docsearch/docusaurus-adapter
# or
npm install @docsearch/docusaurus-adapter

Configuration​

Keep @docusaurus/preset-classic, add the adapter plugin, and configure search under themeConfig.docsearch:

docusaurus.config.mjs
export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indices: [{ name: 'YOUR_INDEX_NAME' }],
      askAi: {
        assistantId: 'YOUR_ASSISTANT_ID',
      },
      sidePanel: true,
      contextualSearch: true,
      searchPage: { path: 'search' },
    },
  },
};

Configuration Key​

Use themeConfig.docsearch as the only adapter configuration key.

The adapter doesn't read themeConfig.algolia, which avoids built-in Docusaurus search-theme validation conflicts when you want newer DocSearch options like Agent Studio and the sidepanel.

Search Page​

The adapter ships a full search page (enabled by default at /search) with faceted filtering, an accessible "Load more" pagination, recent searches, and "Browse by section" shortcuts. Disable it with searchPage: false, or change its path with searchPage: { path: 'search' }.

Facets​

By default the sidebar exposes a single "Section" facet built from the hierarchy.lvl0 attribute. Configure your own refinement lists with searchPage.facets:

docusaurus.config.mjs
export default {
  themeConfig: {
    docsearch: {
      // ...
      searchPage: {
        path: 'search',
        facets: [
          { attribute: 'hierarchy.lvl0', label: 'Section' },
          { attribute: 'type', label: 'Type' },
        ],
      },
    },
  },
};

Each facet is a disjunctive (OR) refinement list. Active refinements are reflected in the URL so filtered searches are shareable.

Analytics​

When insights: true is set (the same flag used by the modal), the search page enables Algolia click analytics and sends clickedObjectIDsAfterSearch events when a result is opened, so full-page searches feed relevance tuning just like the modal.

Customizing Search UI (SearchBar/SearchPage)​

If you want to customize search behavior or UI, customize the adapter theme components (@theme/SearchBar and @theme/SearchPage) from the adapter integration path.

This keeps your customization aligned with DocSearch feature updates and avoids coupling to the built-in Docusaurus Algolia theme implementation.