Setting Up Algolia DocSearch in Docusaurus

May 9, 2025 (1y ago) · 4 min read

Docusaurus

Originally published on LinkedIn, 9 May 2025. Republished here with light editing.

Introduction#

This guide will walk you through the complete process of setting up Algolia DocSearch in your Docusaurus project. Algolia DocSearch provides powerful search capabilities for your documentation website, allowing users to quickly find relevant content.

Prerequisites#

  • A Docusaurus website (v2.x or v3.x)
  • An Algolia account (free tier is available)
  • Your website deployed and accessible online

Step 1: Sign Up for Algolia#

  1. Go to Algolia's website and create an account
  2. Once registered, you'll receive an Application ID and API keys
  3. Note down your Application ID, Search API Key, and Write API Key

Step 2: Configure Docusaurus#

In your Docusaurus project, open the docusaurus.config.ts (or docusaurus.config.js) file and add the Algolia configuration:

// docusaurus.config.ts
export default {
  // ... existing configuration
  themeConfig: {
    // ... other theme config
    algolia: {
      // The application ID provided by Algolia
      appId: 'YOUR_APP_ID',

      // Public API key: it is safe to commit it
      apiKey: 'YOUR_SEARCH_API_KEY', // Use the Search API Key, not the Write API Key

      indexName: 'YOUR_INDEX_NAME', // Choose a meaningful name for your index

      // Optional: see doc section below
      contextualSearch: true,

      // Optional: Specify domains where the navigation should occur through window.location instead on history.push
      externalUrlRegex: 'external\\.com|domain\\.com',

      // Optional: Algolia search parameters
      searchParameters: {},

      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',

      // Optional: whether the insights feature is enabled or not on Docsearch
      insights: false,
    },
  },
};

Replace the placeholder values with your actual Algolia credentials.

Step 3: Verify Domain Ownership#

Algolia requires verification of domain ownership before crawling your site:

  1. Go to the Algolia dashboard
  2. Navigate to Crawler > New Crawler
  3. During setup, you'll be asked to verify your domain
  4. Choose the "robots.txt" verification method
  5. Add the provided verification line to your robots.txt file

If you don't have a robots.txt file, create one in the static directory of your Docusaurus project:

User-agent: *
Allow: /

# Algolia-Crawler-Verif: YOUR_VERIFICATION_CODE

Sitemap: https://your-website-url.com/sitemap.xml

Step 4: Create and Configure the Crawler#

  1. In the Algolia dashboard, go to Crawler > New Crawler
  2. Enter a crawler name (this will be your index name)
  3. Set your website URL as the start URL
  4. Choose "Technical documentation" as the content type
  5. Select "Docusaurus v2.x or v3.x" as the template
  6. Click "Create"

After creating the crawler, you'll need to configure it:

  1. Verify your crawler settings match your website structure
  2. Ensure the index name in the crawler matches the one in your Docusaurus configuration
  3. Save your configuration

Step 5: Run the Crawler#

  1. In the Algolia dashboard, navigate to your crawler
  2. Click "Run Crawler"
  3. Wait for the crawling process to complete
  4. Check that records have been added to your index

Step 6: Deploy Your Website#

Deploy your Docusaurus site with the updated configuration:

git add .
git commit -m "Add Algolia DocSearch configuration"
git push

Step 7: Test the Search Functionality#

  1. Visit your deployed website
  2. Click on the search icon in the header
  3. Type a query related to your content
  4. Verify that search results appear and links work correctly

Troubleshooting#

No Search Results#

If you don't see any search results:

  1. Check if your crawler has successfully indexed your site
  2. Verify that the index name in your configuration matches the crawler's index name
  3. Ensure your API keys are correct

If clicking on search results leads to "Page Not Found" errors:

  1. Remove or adjust the replaceSearchResultPathname configuration in your docusaurus.config.ts:
// Comment out this section if it's causing issues
/*
replaceSearchResultPathname: {
  from: '/docs/',
  to: '/',
},
*/
  1. Re-deploy your website
  2. Re-run the crawler if necessary

Empty Index (0 Records)#

If your index shows "No records yet":

  1. Check the crawler logs for any errors
  2. Verify that your site is accessible to the crawler
  3. Ensure your crawler configuration is correct
  4. Try running the crawler again

Additional Tips#

  1. Contextual Search: Keep contextualSearch: true to ensure search results are relevant to the current language and version of your docs.
  2. Custom Styling: You can customize the appearance of the search modal by adding CSS variables to your custom.css file.
  3. Regular Updates: Re-run your crawler periodically to keep your search index updated with new content.
  4. Multiple Indexes: If you have different types of content (docs, blog, etc.), you might need multiple indexes or a unified search approach.

Conclusion#

You've successfully set up Algolia DocSearch for your Docusaurus website! Your users can now quickly find relevant content using the powerful search functionality. Remember to update your search index regularly by re-running the crawler whenever you add significant new content.

For more advanced configurations, refer to the Algolia DocSearch documentation and the Docusaurus search documentation.

LinkedIn