Skip to main content
The @docsearch/docusaurus-adapter is the recommended way to add DocSearch to your Docusaurus site. It provides full access to the latest DocSearch features, including Ask AI with sidepanel support, without waiting for Docusaurus core updates.

​
Why Use the Adapter?

Docusaurus ships with built-in Algolia search integration (@docusaurus/theme-search-algolia), but the adapter offers several advantages:
  • Faster Access to New Features: Get the latest DocSearch capabilities immediately
  • Ask AI Support: Full support for Ask AI sidepanel and modal modes
  • Independent Release Cycle: Updates don’t require waiting for Docusaurus releases
  • Better Feature Compatibility: Direct integration with DocSearch features

​
Installation

1

Install the adapter package

Add the adapter to your Docusaurus project:
npm install @docsearch/docusaurus-adapter
2

Configure the adapter

Add the adapter plugin to your docusaurus.config.js (or .mjs, .ts) 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',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
};
Keep @docusaurus/preset-classic in your configuration. The adapter works alongside it.
3

Remove conflicting search plugins (optional)

If you previously used @docusaurus/theme-search-algolia, you can remove it as the adapter provides the same functionality:
// Remove this from your config if present
themes: ['@docusaurus/theme-search-algolia']

​
Configuration Options

​
Basic Configuration

The minimum required configuration:
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
  },
}
Enable contextual search to filter results based on the current page context (version, language, etc.):
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    contextualSearch: true,
  },
}
Contextual search automatically adds facet filters based on your Docusaurus site structure.

​
Search Page

Configure a dedicated search results page:
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    searchPagePath: 'search',
  },
}
Set to false to disable the search page: 
searchPagePath: false,

​
URL Transformation

Transform search result URLs to match your site structure:
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    replaceSearchResultPathname: {
      from: '/docs/',
      to: '/documentation/',
    },
  },
}

​
External URLs

Handle external URLs in search results:
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    externalUrlRegex: 'external\\.com|domain\\.com',
  },
}

​
Ask AI Integration

Enable Ask AI to provide conversational search powered by Algolia’s AI:
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    askAi: {
      assistantId: 'YOUR_ASSISTANT_ID',
    },
  },
}
Enable the sidepanel for a better AI chat experience:
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    askAi: {
      assistantId: 'YOUR_ASSISTANT_ID',
      sidePanel: true,
    },
  },
}

​
Suggested Questions

Enable suggested questions on the Ask AI start screen:
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    askAi: {
      assistantId: 'YOUR_ASSISTANT_ID',
      sidePanel: true,
      suggestedQuestions: true,
    },
  },
}

​
Advanced Sidepanel Configuration

Customize sidepanel appearance and behavior:
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    askAi: {
      assistantId: 'YOUR_ASSISTANT_ID',
      sidePanel: {
        variant: 'overlay', // or 'inline'
        pushSelector: '#__docusaurus',
        hideButton: false,
        keyboardShortcuts: { 'Ctrl/Cmd+Shift+A': true },
      },
    },
  },
}

​
Advanced Configuration

​
Search Parameters

Customize Algolia search parameters:
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    searchParameters: {
      facetFilters: ['language:en', ['filter1', 'filter2']],
      hitsPerPage: 10,
    },
  },
}

​
Translations

Customize UI text and button labels:
docusaurus.config.mjs
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    placeholder: 'Search documentation',
    translations: {
      button: {
        buttonText: 'Search',
        buttonAriaLabel: 'Search documentation',
      },
      modal: {
        searchBox: {
          resetButtonTitle: 'Clear',
          cancelButtonText: 'Cancel',
        },
        footer: {
          selectText: 'to select',
          navigateText: 'to navigate',
          closeText: 'to close',
        },
      },
    },
  },
}

​
docsearch vs algolia Configuration Keys

​
Customizing Theme Components

If you need to customize search behavior or UI, you can swizzle the adapter’s theme components:

​
SearchBar Component

npm run swizzle @docsearch/docusaurus-adapter SearchBar
This creates a customizable version at src/theme/SearchBar/index.tsx in your project.

​
SearchPage Component

npm run swizzle @docsearch/docusaurus-adapter SearchPage
This creates a customizable version at src/theme/SearchPage/index.tsx in your project.
Swizzling adapter components keeps your customization aligned with DocSearch feature updates.

​
Complete Example

Here’s a full configuration example with all common options:
docusaurus.config.mjs
export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      
      // Ask AI configuration
      askAi: {
        assistantId: 'YOUR_ASSISTANT_ID',
        sidePanel: {
          variant: 'inline',
          pushSelector: '#__docusaurus',
        },
        suggestedQuestions: true,
      },
      
      // Docusaurus-specific options
      contextualSearch: true,
      searchPagePath: 'search',
      externalUrlRegex: 'external\\.com',
      
      // Search parameters
      searchParameters: {
        facetFilters: ['language:en'],
      },
      
      // UI customization
      placeholder: 'Search docs',
      translations: {
        button: {
          buttonText: 'Search',
        },
      },
    },
  },
};

​
Troubleshooting

​
Search not appearing

  1. Verify the adapter is in the plugins array
  2. Check that your credentials are correct
  3. Ensure your index exists and has data

​
Contextual search not working

  1. Enable contextualSearch: true in config
  2. Verify your crawler configuration includes version/language facets
  3. Check that facet attributes are correctly indexed

​
Ask AI not showing

  1. Verify you have a valid assistantId
  2. Ensure your plan includes Ask AI access
  3. Check browser console for errors

​
Next Steps

API Reference

Explore all available configuration options

Styling

Customize the appearance of DocSearch

Ask AI

Learn more about Ask AI features

Crawler Setup

Configure the DocSearch crawler

Build docs developers (and LLMs) love

Get started for freeTalk to us