> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/algolia/docsearch/llms.txt
> Use this file to discover all available pages before exploring further.

# Docusaurus Integration

> Learn how to integrate DocSearch with Docusaurus using the official adapter

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

<Steps>
  <Step title="Install the adapter package">
    Add the adapter to your Docusaurus project:

    <CodeGroup>
      ```bash npm theme={null}
      npm install @docsearch/docusaurus-adapter
      ```

      ```bash yarn theme={null}
      yarn add @docsearch/docusaurus-adapter
      ```

      ```bash pnpm theme={null}
      pnpm add @docsearch/docusaurus-adapter
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure the adapter">
    Add the adapter plugin to your `docusaurus.config.js` (or `.mjs`, `.ts`) and configure search under `themeConfig.docsearch`:

    ```js title="docusaurus.config.mjs" theme={null}
    export default {
      plugins: ['@docsearch/docusaurus-adapter'],
      themeConfig: {
        docsearch: {
          appId: 'YOUR_APP_ID',
          apiKey: 'YOUR_SEARCH_API_KEY',
          indexName: 'YOUR_INDEX_NAME',
        },
      },
    };
    ```

    <Note>
      Keep `@docusaurus/preset-classic` in your configuration. The adapter works alongside it.
    </Note>
  </Step>

  <Step title="Remove conflicting search plugins (optional)">
    If you previously used `@docusaurus/theme-search-algolia`, you can remove it as the adapter provides the same functionality:

    ```js theme={null}
    // Remove this from your config if present
    themes: ['@docusaurus/theme-search-algolia']
    ```
  </Step>
</Steps>

## Configuration Options

### Basic Configuration

The minimum required configuration:

```js title="docusaurus.config.mjs" theme={null}
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
  },
}
```

### Contextual Search

Enable contextual search to filter results based on the current page context (version, language, etc.):

```js title="docusaurus.config.mjs" theme={null}
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    contextualSearch: true,
  },
}
```

<Note>
  Contextual search automatically adds facet filters based on your Docusaurus site structure.
</Note>

### Search Page

Configure a dedicated search results page:

```js title="docusaurus.config.mjs" theme={null}
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:

```js theme={null}
searchPagePath: false,
```

### URL Transformation

Transform search result URLs to match your site structure:

```js title="docusaurus.config.mjs" theme={null}
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:

```js title="docusaurus.config.mjs" theme={null}
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:

### Modal Mode

```js title="docusaurus.config.mjs" theme={null}
themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    askAi: {
      assistantId: 'YOUR_ASSISTANT_ID',
    },
  },
}
```

### Sidepanel Mode (Recommended)

Enable the sidepanel for a better AI chat experience:

```js title="docusaurus.config.mjs" theme={null}
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:

```js title="docusaurus.config.mjs" theme={null}
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:

```js title="docusaurus.config.mjs" theme={null}
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:

```js title="docusaurus.config.mjs" theme={null}
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:

```js title="docusaurus.config.mjs" theme={null}
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

<Tabs>
  <Tab title="docsearch (Recommended)">
    Use `themeConfig.docsearch` for the canonical configuration:

    ```js title="docusaurus.config.mjs" theme={null}
    export default {
      plugins: ['@docsearch/docusaurus-adapter'],
      themeConfig: {
        docsearch: {
          appId: 'YOUR_APP_ID',
          apiKey: 'YOUR_SEARCH_API_KEY',
          indexName: 'YOUR_INDEX_NAME',
        },
      },
    };
    ```
  </Tab>

  <Tab title="algolia (Legacy)">
    `themeConfig.algolia` is supported for backward compatibility:

    ```js title="docusaurus.config.mjs" theme={null}
    export default {
      plugins: ['@docsearch/docusaurus-adapter'],
      themeConfig: {
        algolia: {
          appId: 'YOUR_APP_ID',
          apiKey: 'YOUR_SEARCH_API_KEY',
          indexName: 'YOUR_INDEX_NAME',
        },
      },
    };
    ```

    <Warning>
      Do not define both `docsearch` and `algolia` keys at the same time. Use `docsearch` to avoid validation conflicts with newer features.
    </Warning>
  </Tab>
</Tabs>

## Customizing Theme Components

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

### SearchBar Component

```bash theme={null}
npm run swizzle @docsearch/docusaurus-adapter SearchBar
```

This creates a customizable version at `src/theme/SearchBar/index.tsx` in your project.

### SearchPage Component

```bash theme={null}
npm run swizzle @docsearch/docusaurus-adapter SearchPage
```

This creates a customizable version at `src/theme/SearchPage/index.tsx` in your project.

<Note>
  Swizzling adapter components keeps your customization aligned with DocSearch feature updates.
</Note>

## Complete Example

Here's a full configuration example with all common options:

```js title="docusaurus.config.mjs" theme={null}
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

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api/configuration">
    Explore all available configuration options
  </Card>

  <Card title="Styling" icon="palette" href="/concepts/styling">
    Customize the appearance of DocSearch
  </Card>

  <Card title="Ask AI" icon="sparkles" href="/concepts/ask-ai">
    Learn more about Ask AI features
  </Card>

  <Card title="Crawler Setup" icon="spider" href="/crawler/configuration">
    Configure the DocSearch crawler
  </Card>
</CardGroup>