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

1. Install the adapter package

   Add the adapter to your Docusaurus project:

   npm

   npm install @docsearch/docusaurus-adapter
   
2. Configure the adapter

   Add the adapter plugin to your docusaurus.config.js (or .mjs, .ts) and configure search under themeConfig.docsearch:

   docusaurus.config.mjs

   export default {
     plugins: ['@docsearch/docusaurus-adapter'],
     themeConfig: {
       docsearch: {
         appId: 'YOUR_APP_ID',
         apiKey: 'YOUR_SEARCH_API_KEY',
         indexName: 'YOUR_INDEX_NAME',
       },
     },
   };
   

   Keep @docusaurus/preset-classic in your configuration. The adapter works alongside it.

3. Remove conflicting search plugins (optional)

   If you previously used @docusaurus/theme-search-algolia, you can remove it as the adapter provides the same functionality:

   // Remove this from your config if present
   themes: ['@docusaurus/theme-search-algolia']
   

Configuration Options

Basic Configuration

The minimum required configuration:

docusaurus.config.mjs

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.):

docusaurus.config.mjs

themeConfig: {
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    contextualSearch: true,
  },
}

Contextual search automatically adds facet filters based on your Docusaurus site structure.

Search Page

Configure a dedicated search results page:

docusaurus.config.mjs

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:

searchPagePath: false,

URL Transformation

Transform search result URLs to match your site structure:

docusaurus.config.mjs

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:

docusaurus.config.mjs

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

docusaurus.config.mjs

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:

docusaurus.config.mjs

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:

docusaurus.config.mjs

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:

docusaurus.config.mjs

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:

docusaurus.config.mjs

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:

docusaurus.config.mjs

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

docsearch (Recommended)

Use themeConfig.docsearch for the canonical configuration:

docusaurus.config.mjs

export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
};

algolia (Legacy)

themeConfig.algolia is supported for backward compatibility:

docusaurus.config.mjs

export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
};

Do not define both docsearch and algolia keys at the same time. Use docsearch to avoid validation conflicts with newer features.

Customizing Theme Components

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

SearchBar Component

npm run swizzle @docsearch/docusaurus-adapter SearchBar

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

SearchPage Component

npm run swizzle @docsearch/docusaurus-adapter SearchPage

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

Swizzling adapter components keeps your customization aligned with DocSearch feature updates.

Complete Example

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

docusaurus.config.mjs

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

API Reference

Explore all available configuration options

Styling

Customize the appearance of DocSearch

Ask AI

Learn more about Ask AI features

Crawler Setup

Configure the DocSearch crawler