61 lines
2.1 KiB
Text
61 lines
2.1 KiB
Text
---
|
|
title: 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
|
|
|
|
```bash
|
|
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` (preferred):
|
|
|
|
```js title="docusaurus.config.mjs"
|
|
export default {
|
|
plugins: ['@docsearch/docusaurus-adapter'],
|
|
themeConfig: {
|
|
docsearch: {
|
|
appId: 'YOUR_APP_ID',
|
|
apiKey: 'YOUR_SEARCH_API_KEY',
|
|
indexName: 'YOUR_INDEX_NAME',
|
|
askAi: {
|
|
assistantId: 'YOUR_ASSISTANT_ID',
|
|
sidePanel: true,
|
|
},
|
|
contextualSearch: true,
|
|
},
|
|
},
|
|
};
|
|
```
|
|
|
|
## `docsearch` vs `algolia` keys
|
|
|
|
- `themeConfig.docsearch` is the canonical key.
|
|
- `themeConfig.algolia` is supported as a backward-compatible alias.
|
|
- Do not define both keys at the same time.
|
|
|
|
Using `themeConfig.docsearch` helps avoid built-in Docusaurus search-theme validation conflicts when you want newer DocSearch options like `askAi.sidePanel`.
|
|
|
|
## 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.
|