629fce7902
* feat(askai): Move askai related props under root askai * fix: playwright test case * fix(docusaurus): validate Ask AI options
118 lines
4.1 KiB
Text
118 lines
4.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`:
|
|
|
|
```js title="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.
|
|
|
|
### Client Side Tools
|
|
|
|
Docusaurus serializes `themeConfig` for the browser and removes function values. Configure `askAi.tools` and `sidePanel.tools` in a swizzled `@theme/SearchBar` component instead of `themeConfig.docsearch`:
|
|
|
|
```tsx title="src/theme/SearchBar/index.tsx"
|
|
import type { ToolCalls } from '@docsearch/react';
|
|
import SearchBar from '@theme-original/SearchBar';
|
|
import type { ReactNode } from 'react';
|
|
|
|
const tools: ToolCalls = {
|
|
logMessage: {
|
|
render: () => 'Tool completed.',
|
|
},
|
|
};
|
|
|
|
export default function SearchBarWithTools(): ReactNode {
|
|
return (
|
|
<SearchBar
|
|
askAi={{ assistantId: 'YOUR_ASSISTANT_ID', tools }}
|
|
sidePanel={{ tools }}
|
|
/>
|
|
);
|
|
}
|
|
```
|
|
|
|
Pass `tools` through `askAi` to enable them in the modal, `sidePanel` to enable them in the side panel, or both for both interfaces. Include any other Ask AI or side-panel options when overriding the corresponding object.
|
|
|
|
## 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`:
|
|
|
|
```js title="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.
|