Skip to main content

2️⃣ Implementing Algolia Search in Docusaurus

Algolia DocSearch is a powerful search solution that Docusaurus officially supports. Follow this tutorial to integrate Algolia DocSearch into your Docusaurus site.

Step 1: Apply for Algolia DocSearch​

  1. Visit the DocSearch application page and apply for the program.
  2. Ensure your website is developer documentation or a technical blog, as the service is free for these types of content.
  3. Once approved, you will receive the following credentials:
    • Application ID (appId)
    • Public API Key (apiKey)
    • Index Name

Step 2: Configure Algolia in Docusaurus​

If you are using @docusaurus/preset-classic, Algolia integration is built-in. Simply add the following to your docusaurus.config.js file:

export default {
  // Other configurations...
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID', // Provided by Algolia
      apiKey: 'YOUR_SEARCH_API_KEY', // Public API Key (safe to commit)
      indexName: 'YOUR_INDEX_NAME', // Name of your Algolia index

      // Optional settings
      contextualSearch: true, // Enables contextual search (default)
      searchPagePath: 'search', // Adds a full search page at /search
    },
  },
};

note

If Not Using the Classic Preset​

If your project doesn’t use @docusaurus/preset-classic, you need to install the required package manually:

npm install @docusaurus/theme-search-algolia

Then, add the @docusaurus/theme-search-algolia to your presets or themes configuration in docusaurus.config.js.

Once your site is deployed and the sitemap.xml is accessible, Algolia will automatically trigger the first crawl.

You can customize the DocSearch UI by modifying the /src/css/custom.css file. For example:

custom.css
[data-theme='light'] .DocSearch {
  --docsearch-modal-background: var(--ifm-color-secondary-lighter);
}

[data-theme='dark'] .DocSearch {
  --docsearch-modal-background: var(--ifm-background-color);
}

Options​

Contextual search is enabled by default, ensuring search results are filtered by language and version. To disable it, update your configuration:

docusaurus.config.js
export default {
  themeConfig: {
    algolia: {
      contextualSearch: false, // Disable contextual search
      searchParameters: {
        facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
      },
    },
  },
};

Search Page​

Enable a dedicated search page by setting searchPagePath in your configuration:

docusaurus.config.js
export default {
  themeConfig: {
    algolia: {
      searchPagePath: 'search',
    },
  },
};

This will create a full search experience at /search.

Troubleshooting​

If no search results appear:

  • Force a new crawl using the Algolia dashboard.
  • Check the Algolia dashboard for index issues.
  • Ensure your site’s content is crawlable via the sitemap.xml.
  • Use the recommended Algolia crawler configuration.

For additional help, refer to the Algolia support page.

Congratulations! Your Docusaurus site now has a robust search functionality powered by Algolia DocSearch.