> ## 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 Installation

> Install and configure DocSearch in Docusaurus v3 sites

DocSearch provides a native Docusaurus theme that replaces the default search functionality with Algolia-powered search. The adapter is specifically designed for Docusaurus v3 and integrates seamlessly with the Docusaurus ecosystem.

## Prerequisites

<Note>
  * Docusaurus v3.9.2 or higher
  * Node.js 20.0 or higher
  * React 18.0+ or React 19.0+
</Note>

## Installation

Install the `@docsearch/docusaurus-adapter` package:

<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>

<Note>
  Don't have your Algolia credentials yet? [Apply to DocSearch](https://docsearch.algolia.com/apply) to get started for free.
</Note>

## Configuration

<Steps>
  <Step title="Add to Docusaurus config">
    Configure DocSearch in your `docusaurus.config.js` file using the `themeConfig.docsearch` option:

    ```javascript docusaurus.config.js theme={null}
    export default {
      // ... other config
      themeConfig: {
        docsearch: {
          appId: 'YOUR_APP_ID',
          apiKey: 'YOUR_SEARCH_API_KEY',
          indexName: 'YOUR_INDEX_NAME',
        },
      },
    };
    ```

    <Note>
      The `themeConfig.algolia` configuration is still supported as a backward-compatible alias, but `themeConfig.docsearch` is the recommended approach.
    </Note>
  </Step>

  <Step title="Configure the theme (optional)">
    If you want to customize the search experience, add the theme to your `docusaurus.config.js`:

    ```javascript docusaurus.config.js theme={null}
    export default {
      // ... other config
      themes: ['@docsearch/docusaurus-adapter'],
      themeConfig: {
        docsearch: {
          appId: 'YOUR_APP_ID',
          apiKey: 'YOUR_SEARCH_API_KEY',
          indexName: 'YOUR_INDEX_NAME',
        },
      },
    };
    ```
  </Step>
</Steps>

## Complete Configuration Example

Here's a comprehensive example with common options:

```javascript docusaurus.config.js theme={null}
export default {
  title: 'My Documentation',
  url: 'https://docs.example.com',
  baseUrl: '/',
  
  themes: ['@docsearch/docusaurus-adapter'],
  
  themeConfig: {
    navbar: {
      title: 'My Docs',
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
    
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      
      // Optional: Contextual search filters
      contextualSearch: true,
      
      // Optional: Path for the search page
      searchPagePath: 'search',
      
      // Optional: External URL regex
      externalUrlRegex: 'external\\.com|another-domain\\.com',
      
      // Optional: Replace search results URLs
      replaceSearchResultPathname: {
        from: '/docs/',
        to: '/',
      },
      
      // Optional: Algolia search parameters
      searchParameters: {
        facetFilters: ['language:en', ['version:1.0', 'version:2.0']],
      },
      
      // Optional: Ask AI configuration
      askAi: {
        assistantId: 'YOUR_ASSISTANT_ID',
        sidePanel: true,
      },
    },
  },
};
```

## Configuration Options

### Required Options

<ParamField path="appId" type="string" required>
  Your Algolia application ID.
</ParamField>

<ParamField path="apiKey" type="string" required>
  Your Algolia Search API key (public, search-only key).
</ParamField>

<ParamField path="indexName" type="string" required>
  The name of your Algolia index to search.
</ParamField>

### Search Behavior Options

<ParamField path="contextualSearch" type="boolean">
  Enables contextual search, which filters results based on the current documentation version and language. Defaults to `false`.

  When enabled, DocSearch automatically adds facet filters based on:

  * Current documentation version
  * Current language
  * Current documentation plugin ID
</ParamField>

<ParamField path="searchParameters" type="object">
  Additional Algolia search parameters to apply to all queries.

  ```javascript theme={null}
  searchParameters: {
    facetFilters: ['language:en', 'version:2.0'],
    hitsPerPage: 10,
  }
  ```
</ParamField>

<ParamField path="searchPagePath" type="boolean | string">
  Path to the search page. Set to `false` to disable the search page. Defaults to `'search'`.

  When enabled, adds a "See all results" link at the bottom of the search modal.
</ParamField>

<ParamField path="externalUrlRegex" type="string">
  Regular expression to identify external URLs. Results matching this pattern will open in a new window instead of using client-side routing.

  ```javascript theme={null}
  externalUrlRegex: 'external\\.com|another-domain\\.com'
  ```
</ParamField>

<ParamField path="replaceSearchResultPathname" type="object">
  Replace parts of the search result URLs before navigation.

  ```javascript theme={null}
  replaceSearchResultPathname: {
    from: '/docs/',
    to: '/'
  }
  ```
</ParamField>

### UI Customization Options

<ParamField path="placeholder" type="string">
  Placeholder text for the search input. Defaults to `'Search docs'`.
</ParamField>

<ParamField path="translations" type="object">
  Localized strings for the search interface. Docusaurus automatically provides translations for supported locales.

  ```javascript theme={null}
  translations: {
    button: {
      buttonText: 'Buscar',
      buttonAriaLabel: 'Buscar documentación'
    },
    modal: {
      searchBox: {
        resetButtonTitle: 'Borrar búsqueda',
        cancelButtonText: 'Cancelar'
      }
    }
  }
  ```
</ParamField>

### Ask AI Options

<ParamField path="askAi" type="object">
  Configuration for the Ask AI feature.

  ```javascript theme={null}
  askAi: {
    assistantId: 'YOUR_ASSISTANT_ID',
    sidePanel: true,
    apiKey: 'YOUR_AI_API_KEY',  // Optional, uses search apiKey by default
    appId: 'YOUR_AI_APP_ID',    // Optional, uses search appId by default
    indexName: 'YOUR_AI_INDEX', // Optional, uses search indexName by default
    suggestedQuestions: true,   // Show suggested questions
  }
  ```
</ParamField>

<ParamField path="askAi.assistantId" type="string" required>
  The Algolia Assistant ID for Ask AI functionality.
</ParamField>

<ParamField path="askAi.sidePanel" type="boolean">
  Enable the side panel UI for Ask AI. When `true`, Ask AI opens in a side panel instead of replacing the search modal. Defaults to `false`.
</ParamField>

<ParamField path="askAi.suggestedQuestions" type="boolean">
  Show suggested questions in the Ask AI interface. Defaults to `false`.
</ParamField>

<ParamField path="askAi.apiKey" type="string">
  API key for Ask AI. If not provided, uses the main `apiKey`.
</ParamField>

<ParamField path="askAi.appId" type="string">
  App ID for Ask AI. If not provided, uses the main `appId`.
</ParamField>

<ParamField path="askAi.indexName" type="string">
  Index name for Ask AI. If not provided, uses the main `indexName`.
</ParamField>

## Contextual Search

Contextual search automatically filters results based on the current page context. This is especially useful for versioned or multi-language documentation.

```javascript docusaurus.config.js theme={null}
export default {
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      contextualSearch: true,
    },
  },
};
```

With contextual search enabled, DocSearch automatically adds facet filters:

* **Version**: `version:2.0` (based on the current doc version)
* **Language**: `language:en` (based on the current locale)
* **DocPlugin**: `docusaurus_tag:docs-default-current` (based on the plugin ID)

## Multi-Index Search

You can search across multiple Algolia indices:

```javascript docusaurus.config.js theme={null}
export default {
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indices: [
        {
          name: 'docs_v1',
          searchParameters: {
            facetFilters: ['version:1.0']
          }
        },
        {
          name: 'docs_v2',
          searchParameters: {
            facetFilters: ['version:2.0']
          }
        },
        'blog', // Simple string for index without custom parameters
      ],
    },
  },
};
```

## Ask AI Side Panel

The side panel provides a persistent AI assistant alongside your documentation:

```javascript docusaurus.config.js theme={null}
export default {
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      askAi: {
        assistantId: 'YOUR_ASSISTANT_ID',
        sidePanel: true,
        suggestedQuestions: true,
      },
    },
  },
};
```

When `sidePanel: true`, users can:

* Open the side panel with a dedicated button in the navbar
* Keep the panel open while browsing documentation
* Switch between search and Ask AI seamlessly

## Custom Styling

DocSearch inherits Docusaurus theme colors automatically. You can further customize with CSS:

```css src/css/custom.css theme={null}
:root {
  --docsearch-primary-color: var(--ifm-color-primary);
  --docsearch-text-color: var(--ifm-font-color-base);
  --docsearch-spacing: 12px;
  --docsearch-icon-stroke-width: 1.4;
  --docsearch-highlight-color: var(--docsearch-primary-color);
  --docsearch-muted-color: var(--ifm-color-secondary-darkest);
  --docsearch-container-background: rgba(94, 100, 112, 0.8);
  --docsearch-modal-background: var(--ifm-background-color);
  --docsearch-searchbox-background: var(--ifm-background-surface-color);
  --docsearch-footer-background: var(--ifm-background-surface-color);
}

[data-theme='dark'] {
  --docsearch-text-color: var(--ifm-font-color-base);
  --docsearch-container-background: rgba(47, 55, 69, 0.7);
  --docsearch-modal-background: var(--ifm-background-color);
  --docsearch-searchbox-background: var(--ifm-background-surface-color);
  --docsearch-footer-background: var(--ifm-background-surface-color);
  --docsearch-hit-background: var(--ifm-background-surface-color);
  --docsearch-hit-shadow: none;
}
```

## Programmatic Access

You can access DocSearch programmatically in Docusaurus using client modules:

```javascript src/clientModules/searchControl.js theme={null}
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

if (ExecutionEnvironment.canUseDOM) {
  // Wait for DocSearch to initialize
  window.addEventListener('load', () => {
    const searchButton = document.querySelector('.DocSearch-Button');
    
    // Custom button to trigger search
    const customButton = document.getElementById('my-search-button');
    if (customButton && searchButton) {
      customButton.addEventListener('click', () => {
        searchButton.click();
      });
    }
  });
}
```

Register the client module in `docusaurus.config.js`:

```javascript docusaurus.config.js theme={null}
export default {
  clientModules: [
    require.resolve('./src/clientModules/searchControl.js'),
  ],
};
```

## Migration from Algolia Plugin

If you're migrating from `@docusaurus/theme-search-algolia`:

<Steps>
  <Step title="Install the new package">
    ```bash theme={null}
    npm install @docsearch/docusaurus-adapter
    ```
  </Step>

  <Step title="Update configuration">
    Change `themeConfig.algolia` to `themeConfig.docsearch`:

    ```diff docusaurus.config.js theme={null}
      export default {
        themeConfig: {
    -     algolia: {
    +     docsearch: {
            appId: 'YOUR_APP_ID',
            apiKey: 'YOUR_SEARCH_API_KEY',
            indexName: 'YOUR_INDEX_NAME',
          },
        },
      };
    ```
  </Step>

  <Step title="Update deprecated options">
    Replace `searchPagePath` boolean with string or `false`:

    ```diff theme={null}
      docsearch: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
    -   searchPagePath: true,
    +   searchPagePath: 'search',
      }
    ```
  </Step>
</Steps>

<Note>
  The `themeConfig.algolia` configuration continues to work as a backward-compatible alias, so you can migrate at your own pace.
</Note>

## Troubleshooting

### Search not appearing

Ensure you have added the search component to your navbar:

```javascript docusaurus.config.js theme={null}
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};
```

### No results found

Verify your index exists and contains data:

1. Check your Algolia dashboard
2. Ensure your `indexName` matches exactly
3. Verify `apiKey` has search permissions
4. Check that contextual filters aren't too restrictive

### Styling conflicts

If DocSearch styles conflict with your theme:

```css src/css/custom.css theme={null}
/* Reset conflicting styles */
.DocSearch-Button {
  /* Your custom styles */
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/api/configuration">
    Learn about all available configuration options
  </Card>

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

  <Card title="Ask AI" icon="sparkles" href="/concepts/ask-ai">
    Enable AI-powered search assistance
  </Card>

  <Card title="Crawler Configuration" icon="spider" href="/crawler/configuration">
    Configure the DocSearch crawler for your site
  </Card>
</CardGroup>