nikon/docsearch
1
0
Fork 0
Code Activity Actions

fix(docs): remove beta references and clean up (#2975)

Browse source
This commit is contained in:
Paul Jankowski 2026-08-07 11:17:15 -04:00 committed by GitHub
parent 40380d6c43
commit 1bb9a0d69c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 62 additions and 187 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
packages/website/docs/hybrid-mode.mdx
View file

@ -96,8 +96,7 @@ interface HybridSearchProps {
appId: string;
apiKey: string;
keywordIndexName: string;
askAiIndexName: string;
assistantId: string;
agentId: string;
onReady?: () => void;
onOpen?: () => void;
onClose?: () => void;
@ -109,8 +108,7 @@ export function HybridSearch({
appId,
apiKey,
keywordIndexName,
askAiIndexName,
assistantId,
agentId,
onReady,
onOpen,
onClose,
@ -130,15 +128,14 @@ export function HybridSearch({
appId={appId}
apiKey={apiKey}
indices={[keywordIndexName]}
askAi={{ assistantId }}
askAi={{ agentId }}
/>
<SidepanelButton />
<Sidepanel
appId={appId}
apiKey={apiKey}
indexName={askAiIndexName}
assistantId={assistantId}
agentId={agentId}
/>
</DocSearch>
);
@ -147,8 +144,6 @@ export function HybridSearch({
`SidepanelButton` gives users a direct Ask AI entry point. You can omit it without disabling hybrid handoff. Keep `Sidepanel` mounted so it can register before a user submits an Ask AI request.
Use the same index name for `keywordIndexName` and `askAiIndexName` when one index serves both experiences. Pass different names when your Agent Studio setup uses a dedicated content index.
#### React lifecycle callbacks
Put lifecycle callbacks on `DocSearch` so they observe the shared state.
@ -242,8 +237,7 @@ import '@docsearch/css/dist/sidepanel.css';
const appId = 'YOUR_APP_ID';
const apiKey = 'YOUR_SEARCH_API_KEY';
const keywordIndexName = 'YOUR_KEYWORD_INDEX_NAME';
const askAiIndexName = 'YOUR_ASK_AI_INDEX_NAME';
const assistantId = 'YOUR_ASSISTANT_ID';
const agentId = 'YOUR_AGENT_ID';
const mobileQuery = window.matchMedia('(max-width: 768px)');
let search: DocSearchInstance | undefined;
@ -253,8 +247,7 @@ panel = sidepanel({
container: '#docsearch-sidepanel',
appId,
apiKey,
indexName: askAiIndexName,
assistantId,
agentId,
onReady: () => {
document.body.setAttribute('data-sidepanel-ready', '');
},
@ -272,7 +265,7 @@ search = docsearch({
appId,
apiKey,
indices: [keywordIndexName],
askAi: { assistantId },
askAi: agentId,
interceptAskAiEvent: (initialMessage) => {
if (mobileQuery.matches) {
return false;
@ -365,7 +358,7 @@ export default {
apiKey: 'YOUR_SEARCH_API_KEY',
indices: [{ name: 'YOUR_INDEX_NAME' }],
askAi: {
assistantId: 'YOUR_ASSISTANT_ID',
agentId: 'YOUR_AGENT_ID',
},
sidePanel: true,
contextualSearch: true,
@ -375,7 +368,7 @@ export default {
};
```
The adapter requires `askAi` to be an object with `assistantId`; it doesn't accept the string shorthand in Docusaurus configuration. It also requires `askAi` whenever `sidePanel` is set.
The adapter requires `askAi` to be an object with `agentId`; it doesn't accept the string shorthand in Docusaurus configuration. It also requires `askAi` whenever `sidePanel` is set.
Don't put `sidePanel` inside `askAi`. Don't configure this adapter under `themeConfig.algolia`. If you need function-valued custom tools, pass them through a swizzled `@theme/SearchBar` component because Docusaurus removes functions while serializing theme configuration.

2
packages/website/docs/migrating-from-v4.mdx
View file

@ -10,7 +10,7 @@ DocSearch v5 separates keyword search from the AI experience and uses Agent Stud
Review the complete [v5 breaking changes](./v5-breaking-changes) before releasing.
## 1. Upgrade the beta packages
## 1. Upgrade packages
Upgrade every DocSearch package in the integration together with the `^5` range.

14
packages/website/docs/packages/core/api.mdx
View file

@ -1,6 +1,6 @@
---
title: Core API reference
description: API reference for @docsearch/core v5 beta.
description: API reference for @docsearch/core v5.
toc_max_heading_level: 2
---
@ -8,6 +8,18 @@ toc_max_heading_level: 2
`DocSearch` is a ref-forwarding React provider.
### `appId`
> `type: string` | **optional**
Optional parent level application ID. If this is set, `appId` won't need to be set on the child Modal/Sidepanel.
### `apiKey`
> `type: string` | **optional**
Optional parent level search API key. If this is set, `apiKey` won't need to be set on the child Modal/Sidepanel.
### `children`
> `type: React.ReactNode` | **required**

8
packages/website/docs/packages/core/overview.mdx
View file

@ -1,6 +1,6 @@
---
title: Core package
description: Understand the shared state and controls in @docsearch/core v5 beta.
description: Understand the shared state and controls in @docsearch/core v5.
---
import TabItem from '@theme/TabItem';
@ -8,12 +8,6 @@ import Tabs from '@theme/Tabs';
`@docsearch/core` provides the React state shared by DocSearch views. It owns open and close state, keyboard events, theme selection, lifecycle callbacks, initial queries, and imperative controls. It doesn't render a search interface by itself.
:::info v5 beta
These instructions use the `^5` range.
:::
## Install
<Tabs groupId="package-manager" aria-label="Package manager">

10
packages/website/docs/packages/css/styling.mdx
View file

@ -1,18 +1,12 @@
---
title: Style DocSearch
description: Load and customize the DocSearch v5 beta CSS.
description: Load and customize the DocSearch v5 CSS.
---
import TabItem from '@theme/TabItem';
import Tabs from '@theme/Tabs';
`@docsearch/css` contains the styles for the search button, modal, Agent Studio responses, and Sidepanel.
:::info v5 beta
These instructions use the `^5` range.
:::
`@docsearch/css` contains the styles for the search button, modal, and Sidepanel.
## Install and import

2
packages/website/docs/packages/docusaurus-adapter/migrating-from-v4.mdx
View file

@ -1,6 +1,6 @@
---
title: Migrate the Docusaurus adapter from v4
description: Move a Docusaurus DocSearch adapter configuration from v4 to the v5 beta.
description: Move a Docusaurus DocSearch adapter configuration from v4 to the v5.
---
import Tabs from '@theme/Tabs';

24
packages/website/docs/packages/modal/api.mdx
View file

@ -1,6 +1,6 @@
---
title: Modal API reference
description: API reference for @docsearch/modal v5 beta.
description: API reference for @docsearch/modal v5.
---
## `DocSearchButton`
@ -41,16 +41,10 @@ Public API key with search permission.
> `type: Array<string | DocSearchIndex>` | **required**
Indices to search. You can omit this prop only if you use the deprecated [`indexName`](#indexname).
The list of indices and their optional configuration used for search.
### Search props
#### `indexName`
> `type: string` | **optional** | **deprecated**
Sets one index to search. Use [`indices`](#indices) instead.
#### `facets`
> `type: Array<{ key: string; label?: string }>` | **optional**
@ -63,12 +57,6 @@ Adds filter controls that use facet values from the configured indices. Defaults
Sets the search input placeholder. Defaults to `Search docs`. A translation can override this value.
#### `searchParameters`
> `type: SearchParamsObject` | **optional** | **deprecated**
Merges parameters into search requests. Set parameters on each [`indices`](#indices) entry instead.
#### `maxResultsPerGroup`
> `type: number` | **optional**
@ -213,7 +201,7 @@ The component receives its active state and close behavior from `DocSearch`. It
The object form of [`askAi`](#askai). It accepts the following fields.
### `assistantId`
### `agentId`
> `type: string` | **required**
@ -231,12 +219,6 @@ Overrides the root `appId` for Agent Studio.
Overrides the root `apiKey` for Agent Studio.
### `indexName`
> `type: string` | **optional**
Sets the index for conversation storage and Agent Studio requests. Defaults to the first root index.
### `suggestedQuestions`
> `type: boolean` | **optional**

14
packages/website/docs/packages/modal/overview.mdx
View file

@ -8,13 +8,7 @@ import Tabs from '@theme/Tabs';
`@docsearch/modal` provides the DocSearch search button, keyword-search modal, and Agent Studio-enabled modal for React. Render these components inside the `DocSearch` provider from `@docsearch/core`.
:::info v5 beta
These instructions use the `^5` range. Use the same range for every DocSearch package.
:::
For the complete component workflow, see the [Composable API guide](/docs/composable-api).
For the complete component workflow, see the [Composable API guide](../../composable-api).
## Install
@ -77,7 +71,7 @@ Use a search-only API key. Don't expose an Algolia Admin API key in browser code
## Add Agent Studio
In v5, Ask AI uses Agent Studio. Pass an Agent Studio agent ID through `askAi.assistantId`. There's no `agentStudio` boolean in the v5 API.
In v5, Ask AI uses Agent Studio. Pass an Agent Studio agent ID through `askAi`. There's no `agentStudio` boolean in the v5 API.
```tsx title="Search.tsx"
import { DocSearch } from '@docsearch/core';
@ -93,9 +87,7 @@ export function Search() {
appId="YOUR_APPLICATION_ID"
apiKey="YOUR_SEARCH_API_KEY"
indices={['YOUR_INDEX_NAME']}
askAi={{
assistantId: 'YOUR_AGENT_ID',
}}
askAi="YOUR_AGENT_ID"
/>
</DocSearch>
);

41
packages/website/docs/packages/overview.mdx
View file

@ -40,45 +40,10 @@ Use the AI-capable integration when you have an Agent Studio assistant.
- JavaScript: use the default `@docsearch/js` export.
- React: render `DocSearchAI` from `@docsearch/react`.
Create and configure the assistant before adding it to DocSearch. See [Get started with Agent Studio](/docs/agent-studio/getting-started).
Create and configure the assistant before adding it to DocSearch. See [Get started with Agent Studio](../agent-studio/getting-started).
### Composable and hybrid experiences
Use the [Composable API](/docs/composable-api) to control the provider, button, and modal separately. Use [hybrid mode](/docs/hybrid-mode) to combine the modal with the AI Sidepanel.
Use the [Composable API](../composable-api) to control the provider, button, and modal separately. Use [hybrid mode](../hybrid-mode) to combine the modal with the AI Sidepanel.
## Beta version
Install the v5 beta with the caret range:
<Tabs groupId="package-manager" aria-label="Package manager">
<TabItem value="npm" label="npm">
```bash
npm install @docsearch/js@^5 @docsearch/css@^5
```
</TabItem>
<TabItem value="yarn" label="Yarn">
```bash
yarn add @docsearch/js@^5 @docsearch/css@^5
```
</TabItem>
<TabItem value="pnpm" label="pnpm">
```bash
pnpm add @docsearch/js@^5 @docsearch/css@^5
```
</TabItem>
<TabItem value="bun" label="Bun">
```bash
bun add @docsearch/js@^5 @docsearch/css@^5
```
</TabItem>
</Tabs>
For an existing v4 integration, read [Migrate from v4](/docs/migrating-from-v4) and [v5 breaking changes](/docs/v5-breaking-changes).
For an existing v4 integration, read [Migrate from v4](../migrating-from-v4) and [v5 breaking changes](../v5-breaking-changes).

15
packages/website/docs/packages/sidepanel-js/api.mdx
View file

@ -1,6 +1,6 @@
---
title: Sidepanel JS API reference
description: API reference for @docsearch/sidepanel-js v5 beta.
description: API reference for @docsearch/sidepanel-js v5.
toc_max_heading_level: 2
---
@ -42,20 +42,12 @@ Algolia application ID.
Public API key with search permission.
#### `assistantId`
#### `agentId`
> `type: string` | **required**
Agent Studio agent ID.
#### `indexName`
> `type: string` | **required**
Primary index for Agent Studio and conversation storage.
The public `SidepanelProps` type in `5` doesn't include the React Sidepanel's top-level `searchParameters` field.
### UI props
#### `theme`
@ -135,8 +127,7 @@ const assistant = sidepanel({
container: '#docsearch-sidepanel',
appId: 'YOUR_APPLICATION_ID',
apiKey: 'YOUR_SEARCH_API_KEY',
assistantId: 'YOUR_AGENT_ID',
indexName: 'docs',
agentId: 'YOUR_AGENT_ID',
memory: {
enabled: true,
userToken: userMemoryToken,

20
packages/website/docs/packages/sidepanel-js/getting-started.mdx
View file

@ -1,6 +1,6 @@
---
title: Sidepanel JS package
description: Mount and control the v5 beta Agent Studio Sidepanel without React application code.
description: Mount and control the v5 Sidepanel without React application code.
---
import TabItem from '@theme/TabItem';
@ -8,12 +8,6 @@ import Tabs from '@theme/Tabs';
`@docsearch/sidepanel-js` mounts the Agent Studio Sidepanel into an existing HTML element. It bundles its rendering dependencies and returns an imperative instance.
:::info v5 beta
These instructions use the `^5` range.
:::
## Install
<Tabs groupId="package-manager" aria-label="Package manager">
@ -65,19 +59,14 @@ const assistant = sidepanel({
container: '#docsearch-sidepanel',
appId: 'YOUR_APPLICATION_ID',
apiKey: 'YOUR_SEARCH_API_KEY',
assistantId: 'YOUR_AGENT_ID',
indexName: 'YOUR_INDEX_NAME',
agentId: 'YOUR_AGENT_ID',
onReady() {
console.info('DocSearch sidepanel is ready');
},
});
document.querySelector('#ask-docs').addEventListener('click', () => {
assistant.open();
});
```
Use a search-only API key. The `assistantId` is an Agent Studio agent ID. V5 doesn't provide an `agentStudio` switch.
Use a search-only API key. The `agentId` is an Agent Studio agent ID.
## Open with a question
@ -111,8 +100,7 @@ Call `assistant.destroy()` before removing the container or remounting another S
container: '#docsearch-sidepanel',
appId: 'YOUR_APPLICATION_ID',
apiKey: 'YOUR_SEARCH_API_KEY',
assistantId: 'YOUR_AGENT_ID',
indexName: 'YOUR_INDEX_NAME',
agentId: 'YOUR_AGENT_ID',
});
</script>
```

22
packages/website/docs/packages/sidepanel/advanced-use-cases.mdx
View file

@ -12,8 +12,7 @@ Use the `inline` panel variant to add a margin to the first element that matches
<Sidepanel
appId="YOUR_APPLICATION_ID"
apiKey="YOUR_SEARCH_API_KEY"
assistantId="YOUR_AGENT_ID"
indexName="YOUR_INDEX_NAME"
agentId="YOUR_AGENT_ID"
variant="inline"
side="left"
pushSelector="#documentation"
@ -26,7 +25,7 @@ Keep `pushSelector` narrow enough to identify one layout container. The implemen
## Render into another container
Both the floating button and panel default to `document.body`. Set `portalContainer` on the panel and `portalcontainer` on the button to use another element. The button prop is lower-case in the v5 beta API.
Both the floating button and panel default to `document.body`. Set `portalContainer` on the panel and `portalcontainer` on the button to use another element.
```tsx title="AssistantPortal.tsx"
const assistantRoot = document.getElementById('assistant-root');
@ -36,8 +35,7 @@ const assistantRoot = document.getElementById('assistant-root');
<Sidepanel
appId="YOUR_APPLICATION_ID"
apiKey="YOUR_SEARCH_API_KEY"
assistantId="YOUR_AGENT_ID"
indexName="YOUR_INDEX_NAME"
agentId="YOUR_AGENT_ID"
portalContainer={assistantRoot}
/>
</DocSearch>;
@ -72,8 +70,7 @@ export function Support() {
<Sidepanel
appId="YOUR_APPLICATION_ID"
apiKey="YOUR_SEARCH_API_KEY"
assistantId="YOUR_AGENT_ID"
indexName="YOUR_INDEX_NAME"
agentId="YOUR_AGENT_ID"
/>
</DocSearch>
);
@ -104,8 +101,7 @@ const tools = {
<Sidepanel
appId="YOUR_APPLICATION_ID"
apiKey="YOUR_SEARCH_API_KEY"
assistantId="YOUR_AGENT_ID"
indexName="YOUR_INDEX_NAME"
agentId="YOUR_AGENT_ID"
tools={tools}
/>;
```
@ -120,8 +116,7 @@ Pass a server-generated Agent Studio user JWT. `enabled` controls whether memory
<Sidepanel
appId="YOUR_APPLICATION_ID"
apiKey="YOUR_SEARCH_API_KEY"
assistantId="YOUR_AGENT_ID"
indexName="YOUR_INDEX_NAME"
agentId="YOUR_AGENT_ID"
memory={{
enabled: true,
userToken: userMemoryToken,
@ -133,14 +128,13 @@ Don't generate or sign the token in the browser.
## Provide dynamic indices
Use `indices` to select the indices Agent Studio can search at request time. This list is separate from the required `indexName`, which remains the Sidepanel's primary index.
Use `indices` to select the indices Agent Studio can search at request time.
```tsx title="DynamicIndices.tsx"
<Sidepanel
appId="YOUR_APPLICATION_ID"
apiKey="YOUR_SEARCH_API_KEY"
assistantId="YOUR_AGENT_ID"
indexName="docs"
agentId="YOUR_AGENT_ID"
searchParameters={{
docs: { filters: 'version:v5' },
support_articles: { filters: 'visibility:public' },

14
packages/website/docs/packages/sidepanel/api.mdx
View file

@ -1,6 +1,6 @@
---
title: React Sidepanel API reference
description: API reference for @docsearch/sidepanel v5 beta.
description: API reference for @docsearch/sidepanel.
toc_max_heading_level: 2
---
@ -8,7 +8,7 @@ toc_max_heading_level: 2
Render `Sidepanel` inside `DocSearch` from `@docsearch/core`.
Set `theme` on `DocSearch`; `SidepanelProps` omits it. Set lifecycle callbacks such as `onSidepanelOpen` and `onSidepanelClose` on the provider. Don't pass inherited `onOpen` or `onClose` callbacks to `Sidepanel`, because they replace the wrapper's state handlers in this beta.
Set `theme` on `DocSearch`; `SidepanelProps` omits it. Set lifecycle callbacks such as `onSidepanelOpen` and `onSidepanelClose` on the provider. Don't pass inherited `onOpen` or `onClose` callbacks to `Sidepanel`, because they replace the wrapper's state handlers.
### Connection props
@ -24,18 +24,12 @@ Algolia application ID.
Public API key with search permission.
#### `assistantId`
#### `agentId`
> `type: string` | **required**
Agent Studio agent ID.
#### `indexName`
> `type: string` | **required**
Primary index for Agent Studio and conversation storage.
#### `searchParameters`
> `type: Record<string, AgentStudioIndexSearchParameters>` | **optional**
@ -172,7 +166,7 @@ Changes visible and accessible text. `buttonText` applies to the inline variant.
> `type: DocumentFragment | Element | null` | **optional**
Receives the floating button portal. Defaults to `document.body`. This beta prop uses a lower-case `c`.
Receives the floating button portal. Defaults to `document.body`.
The wrapper supplies its click handler and keyboard shortcut configuration from `DocSearch`. An inline button renders at its position in the React tree.

16
packages/website/docs/packages/sidepanel/getting-started.mdx
View file

@ -1,6 +1,6 @@
---
title: Sidepanel package
description: Add the v5 beta Agent Studio Sidepanel to a React application.
description: Add the DocSearch Sidepanel to a React application.
---
import TabItem from '@theme/TabItem';
@ -8,12 +8,6 @@ import Tabs from '@theme/Tabs';
`@docsearch/sidepanel` provides composable React components for an Agent Studio chat panel.
:::info v5 beta
These instructions use the `^5` range. Use the same range for every DocSearch package.
:::
## Install
<Tabs groupId="package-manager" aria-label="Package manager">
@ -65,15 +59,14 @@ export function HelpAssistant() {
<Sidepanel
appId="YOUR_APPLICATION_ID"
apiKey="YOUR_SEARCH_API_KEY"
assistantId="YOUR_AGENT_ID"
indexName="YOUR_INDEX_NAME"
agentId="YOUR_AGENT_ID"
/>
</DocSearch>
);
}
```
Use a search-only API key. The `assistantId` is an Agent Studio agent ID. V5 doesn't provide the legacy Ask AI backend or an `agentStudio` switch.
Use a search-only API key. The `agentId` is an Agent Studio agent ID. V5 doesn't provide the legacy Ask AI backend or an `agentStudio` switch.
The default button and panel float over the page. Press `Control+I` or `Command+I` to toggle the panel, and press `Escape` to close it.
@ -92,8 +85,7 @@ Set the theme and lifecycle callbacks on `DocSearch`.
<Sidepanel
appId="YOUR_APPLICATION_ID"
apiKey="YOUR_SEARCH_API_KEY"
assistantId="YOUR_AGENT_ID"
indexName="YOUR_INDEX_NAME"
agentId="YOUR_AGENT_ID"
/>
</DocSearch>
```

20
packages/website/docs/v5-breaking-changes.mdx
View file

@ -117,22 +117,6 @@ The v5 adapter reads `themeConfig.docsearch` and rejects the former `themeConfig
Replace `searchPagePath` with `searchPage`. Move `askAi.sidePanel` to the root `sidePanel` option. Remove legacy Ask AI credentials and the `askAi.agentStudio` switch. Follow [Migrate the Docusaurus adapter from v4](/docs/packages/docusaurus-adapter/migrating-from-v4) for before-and-after configurations.
### At least one index is required at runtime
Pass `indices` or `indexName`. V5 throws this error when neither produces an index:
```text
Must supply either `indexName` or `indices` for DocSearch to work
```
### `indexName` remains deprecated
`indexName` still works; it isn't removed in v5. If present, DocSearch places it before all `indices` entries. Passing the same index through both options sends duplicate requests.
### Root `searchParameters` remains deprecated
The root option applies only to `indexName`. Move search parameters to each `DocSearchIndex` in `indices`.
### Multiple indices share one result flow
V5 creates one source for each index response and combines hit totals across responses. Result order follows the normalized index order. Review code that assumes one index or source identifier.
@ -211,11 +195,11 @@ See [hybrid mode](/docs/hybrid-mode) for the supported integration.
### Package versions must match
The `5` packages depend on matching beta versions of the other DocSearch packages. Don't mix v4 and v5 packages in a Composable API or Sidepanel tree.
The `v5` packages depend on matching versions of the other DocSearch packages. Don't mix v4 and v5 packages in a Composable API or Sidepanel tree.
### CSS remains a separate install for top-level integrations
Install `@docsearch/css@^5`, then import `@docsearch/css`. For a CDN integration, load `dist/style.css` from the same caret beta range.
Install `@docsearch/css@^5`, then import `@docsearch/css`. For a CDN integration, load `@docsearch/css/dist/style.css`.
## Additive v5 APIs

2
packages/website/docusaurus.config.mjs
View file

@ -190,7 +190,7 @@ export default {
to: 'docs/v4/docsearch',
},
{
label: 'DocSearch v5 beta',
label: 'DocSearch v5',
to: 'docs/packages/overview',
},
],