Skip to main content
Version: 2.0.0-beta.7 🚧

Search

There are a few options you can use to add search to your website:

info

🥇 Docusaurus provides first-class support for Algolia DocSearch.

👥 Other options are maintained by the community: please report bugs to their respective repositories.

🥇 Using Algolia DocSearch#

Docusaurus has official support for Algolia DocSearch.

The service is free in most cases: just apply to the DocSearch program.

It works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API.

If your website is not eligible for the free, hosted version of DocSearch, or if your website sits behind a firewall and is not public, then you can run your own DocSearch crawler.

note

By default, the Docusaurus preset generates a sitemap.xml that the Algolia crawler can use.

Index Configuration#

After applying, your site's DocSearch config should be created at:

https://github.com/algolia/docsearch-configs/blob/master/configs/<indexName>.json

This configuration file can be updated by:

caution

It is highly recommended using a config similar to the Docusaurus 2 website config.

Connecting Algolia#

Docusaurus' own @docusaurus/preset-classic supports an Algolia DocSearch integration.

To connect your docs with Algolia, first add the package to your website:

npm install --save @docusaurus/theme-search-algolia

Then, add an algolia field in your themeConfig. Apply for DocSearch to get your Algolia index and API key.

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    algolia: {      apiKey: 'YOUR_API_KEY',      indexName: 'YOUR_INDEX_NAME',
      // Optional: see doc section below      contextualSearch: true,
      // Optional: see doc section below      appId: 'YOUR_APP_ID',
      // Optional: Algolia search parameters      searchParameters: {},
      //... other Algolia params    },  },};
info

The searchParameters option used to be named algoliaOptions in Docusaurus v1.

Contextual search is mostly useful for versioned Docusaurus sites.

Let's consider you have 2 docs versions, v1 and v2. When you are browsing v2 docs, it would be odd to return search results for the v1 documentation. Sometimes v1 and v2 docs are quite similar, and you would end up with duplicate search results for the same query (one result per version).

To solve this problem, the contextual search feature understands that you are browsing a specific docs version, and will create the search query filters dynamically.

  • browsing /docs/v1/myDoc, search results will only include v1 docs (+ other unversioned pages)
  • browsing /docs/v2/myDoc, search results will only include v2 docs (+ other unversioned pages)
docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    algolia: {      contextualSearch: true,    },  },};
caution

When using contextualSearch: true, the contextual facet filters will be merged with the ones provided with algolia.searchParameters.facetFilters.

Custom Application ID#

When running your own DocSearch crawler, it is required to set the appId configuration key to your own Application ID. If left unset, the appId will fallback to the one used with the free, hosted version of Algolia DocSearch.

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    algolia: {      appId: 'YOUR_APP_ID',    },  },};

By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards.

Still, you can reuse the Infima CSS variables from Docusaurus to style DocSearch by editing the /src/css/custom.css file.

/src/css/custom.css
html[data-theme='light'] .DocSearch {  /* --docsearch-primary-color: var(--ifm-color-primary); */  /* --docsearch-text-color: var(--ifm-font-color-base); */  --docsearch-muted-color: var(--ifm-color-secondary-darkest);  --docsearch-container-background: rgba(94, 100, 112, 0.7);  /* Modal */  --docsearch-modal-background: var(--ifm-color-secondary-lighter);  /* Search box */  --docsearch-searchbox-background: var(--ifm-color-secondary);  --docsearch-searchbox-focus-background: var(--ifm-color-white);  /* Hit */  --docsearch-hit-color: var(--ifm-font-color-base);  --docsearch-hit-active-color: var(--ifm-color-white);  --docsearch-hit-background: var(--ifm-color-white);  /* Footer */  --docsearch-footer-background: var(--ifm-color-white);}
html[data-theme='dark'] .DocSearch {  --docsearch-text-color: var(--ifm-font-color-base);  --docsearch-muted-color: var(--ifm-color-secondary-darkest);  --docsearch-container-background: rgba(47, 55, 69, 0.7);  /* Modal */  --docsearch-modal-background: var(--ifm-background-color);  /* Search box */  --docsearch-searchbox-background: var(--ifm-background-color);  --docsearch-searchbox-focus-background: var(--ifm-color-black);  /* Hit */  --docsearch-hit-color: var(--ifm-font-color-base);  --docsearch-hit-active-color: var(--ifm-color-white);  --docsearch-hit-background: var(--ifm-color-emphasis-100);  /* Footer */  --docsearch-footer-background: var(--ifm-background-surface-color);  --docsearch-key-gradient: linear-gradient(    -26.5deg,    var(--ifm-color-emphasis-200) 0%,    var(--ifm-color-emphasis-100) 100%  );}

Customizing the Algolia search behavior#

Algolia DocSearch supports a list of options that you can pass to the algolia field in the docusaurus.config.js file.

docusaurus.config.js
module.exports = {  themeConfig: {    // ...    algolia: {      apiKey: 'YOUR_API_KEY',      indexName: 'YOUR_INDEX_NAME',      // Options...    },  },};

Editing the Algolia search component#

If you prefer to edit the Algolia search React component, swizzle the SearchBar component in @docusaurus/theme-search-algolia:

npm run swizzle @docusaurus/theme-search-algolia SearchBar

Support#

The Algolia DocSearch team can help you figure out search problems on your site.

You can contact them by email or on Discord.

Docusaurus also has an #algolia channel on Discord.

👥 Using Typesense DocSearch#

Typesense DocSearch works similar to Algolia DocSearch, except that your website is indexed into a Typesense search cluster.

Typesense is an open source instant-search engine that you can either:

Similar to Algolia DocSearch, there are two components:

Read a step-by-step walk-through of how to run typesense-docsearch-scraper here and how to install the Search Bar in your Docusaurus Site here.

You can use a local search plugin for websites where the search index is small and can be downloaded to your users' browsers when they visit your website.

You'll find a list of community-supported local search plugins listed here.

To use your own search, swizzle the SearchBar component in @docusaurus/theme-classic

npm run swizzle @docusaurus/theme-classic SearchBar

This will create a src/themes/SearchBar file in your project folder. Restart your dev server and edit the component, you will see that Docusaurus uses your own SearchBar component now.

Notes: You can alternatively swizzle from Algolia SearchBar and create your own search component from there.