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

• Docusaurus v3.9.2 or higher
• Node.js 20.0 or higher
• React 18.0+ or React 19.0+

Installation

Install the @docsearch/docusaurus-adapter package:

npm

npm install @docsearch/docusaurus-adapter

Don’t have your Algolia credentials yet? Apply to DocSearch to get started for free.

Configuration

1. Add to Docusaurus config

   Configure DocSearch in your docusaurus.config.js file using the themeConfig.docsearch option:

   docusaurus.config.js

   export default {
     // ... other config
     themeConfig: {
       docsearch: {
         appId: 'YOUR_APP_ID',
         apiKey: 'YOUR_SEARCH_API_KEY',
         indexName: 'YOUR_INDEX_NAME',
       },
     },
   };
   

   The themeConfig.algolia configuration is still supported as a backward-compatible alias, but themeConfig.docsearch is the recommended approach.

2. Configure the theme (optional)

   If you want to customize the search experience, add the theme to your docusaurus.config.js:

   docusaurus.config.js

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

Complete Configuration Example

Here’s a comprehensive example with common options:

docusaurus.config.js

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

appId · string · required

Your Algolia application ID.

apiKey · string · required

Your Algolia Search API key (public, search-only key).

indexName · string · required

The name of your Algolia index to search.

Search Behavior Options

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

searchParameters · object

Additional Algolia search parameters to apply to all queries.

searchParameters: {
  facetFilters: ['language:en', 'version:2.0'],
  hitsPerPage: 10,
}

searchPagePath · 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.

externalUrlRegex · string

Regular expression to identify external URLs. Results matching this pattern will open in a new window instead of using client-side routing.

externalUrlRegex: 'external\\.com|another-domain\\.com'

replaceSearchResultPathname · object

Replace parts of the search result URLs before navigation.

replaceSearchResultPathname: {
  from: '/docs/',
  to: '/'
}

UI Customization Options

placeholder · string

Placeholder text for the search input. Defaults to 'Search docs'.

translations · object

Localized strings for the search interface. Docusaurus automatically provides translations for supported locales.

translations: {
  button: {
    buttonText: 'Buscar',
    buttonAriaLabel: 'Buscar documentación'
  },
  modal: {
    searchBox: {
      resetButtonTitle: 'Borrar búsqueda',
      cancelButtonText: 'Cancelar'
    }
  }
}

Ask AI Options

askAi · object

Configuration for the Ask AI feature.

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
}

askAi.assistantId · string · required

The Algolia Assistant ID for Ask AI functionality.

askAi.sidePanel · 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.

askAi.suggestedQuestions · boolean

Show suggested questions in the Ask AI interface. Defaults to false.

askAi.apiKey · string

API key for Ask AI. If not provided, uses the main apiKey.

askAi.appId · string

App ID for Ask AI. If not provided, uses the main appId.

askAi.indexName · string

Index name for Ask AI. If not provided, uses the main indexName.

Contextual Search

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

docusaurus.config.js

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:

docusaurus.config.js

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:

docusaurus.config.js

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:

src/css/custom.css

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

src/clientModules/searchControl.js

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:

docusaurus.config.js

export default {
  clientModules: [
    require.resolve('./src/clientModules/searchControl.js'),
  ],
};

Migration from Algolia Plugin

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

1. Install the new package

   npm install @docsearch/docusaurus-adapter
   
2. Update configuration

   Change themeConfig.algolia to themeConfig.docsearch:

   docusaurus.config.js

     export default {
       themeConfig: {
   -     algolia: {
   +     docsearch: {
           appId: 'YOUR_APP_ID',
           apiKey: 'YOUR_SEARCH_API_KEY',
           indexName: 'YOUR_INDEX_NAME',
         },
       },
     };
   
3. Update deprecated options

   Replace searchPagePath boolean with string or false:

     docsearch: {
       appId: 'YOUR_APP_ID',
       apiKey: 'YOUR_SEARCH_API_KEY',
       indexName: 'YOUR_INDEX_NAME',
   -   searchPagePath: true,
   +   searchPagePath: 'search',
     }
   

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

Troubleshooting

Search not appearing

Ensure you have added the search component to your navbar:

docusaurus.config.js

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:

src/css/custom.css

/* Reset conflicting styles */
.DocSearch-Button {
  /* Your custom styles */
}

Next Steps

Configuration

Learn about all available configuration options

Styling

Customize the appearance of your search

Ask AI

Enable AI-powered search assistance

Crawler Configuration

Configure the DocSearch crawler for your site