Skip to main content

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 for any developer documentation or technical blog: just make sure to read the checklist and apply to the DocSearch program.

DocSearch crawls your website once a week (the schedule is configurable from the web interface) and aggregates 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.

From the old docsearch?

You can read more about migration from the legacy DocSearch infra in our blog post or the DocSearch migration docs.

(Optional) Setup CNAME for GitHub Pages Custom Domain​

Prerequisites​

  1. A Squarespace domain (or any DNS-configurable domains owned)
  2. A GitHub user/org site repository in the <user>/<org>.github.io format. Follow this tutorial to set one up if not yet.

Configuration on GitHub Pages Side​

GitHub Pages is a static site hosting service that serves our custom website at a URL directly from a GitHub repository. Our user site repository automatically publishes updates to a URL of the same name, <user>/<org>.github.io. We need to enable the settings that allow an alternative domain to point to the content hosted in this repository in the following steps

  1. Navigate to our <user>/<org>.github.io repository in the GitHub web application, and select Settings from the navigation menu.
  2. Scroll down to the Code and automation > Pages section.
  3. Note the selected branch and folder in the Source section. GitHub will automatically publish any content committed to this branch in this directory to our website.
  4. In the Custom domain input, enter our Squarespace domain name. For example, www.my-domain.com
  5. Ensure that Enforce HTTPS is selected. Note that it can take up to a day before this option is available.
  6. At the top of the page, select Code from the navigation menu.
  7. Select the branch from the drop-down menu you configured in the Code and automation > Pages > Source section.
  8. You should now see a file entitled CNAME containing your domain name.

Configuration on Domain Provider Side (Squarespace)​

Next, we need to point our custom domain's DNS record to GitHub’s servers.

  1. Navigate to https://account.squarespace.com/domains.

  2. Find the domain name that we have configured our <user>/<org>.github.io repository to point to.

  3. Select DNS Settings from the sidebar navigation.

  4. Add an "A" record with host "@" for each GitHub Pages IP address. Use the dig <user>/<org>.github.io +nostats +nocomments +nocmd command to get this list. At the time of authorship, they were 185.199.108.153, 185.199.110.153, 185.199.111.153, and 185.199.109.153.

  5. Add a "CNAME" record with host "www" to point our subdomain to <user>/<org>.github.io.

    warning

    The CNAME record should always point to <user>.github.io or <organization>.github.io, excluding the repository name

Error loading squarespace-dns.png

Index Configuration​

After your application has been approved and deployed, you will receive an email with all the details for you to add DocSearch to your project. Editing and managing your crawls can be done via the web interface. Indices are readily available after deployment, so manual configuration usually isn't necessary.

tip

It is highly recommended to use a config similar to the Docusaurus v3 website config. Because the problem is a recent update of Docusaurus, since which contextual search is enabled by default. The problem: Algolia's default config for Docusaurus v1 and older Docusaurus v2 versions didn't have an option for this attribute to configure the crawler.

To resolve:

  1. Delete the current index
  2. Directly create the crawler at https://crawler.algolia.com/admin/crawlers/create
  3. Re-run crawler (will create an index).
  4. Redeploy the Docusaurus site.

Connecting Algolia​

Docusaurus' own @docusaurus/preset-classic supports Algolia DocSearch integration. If you use the classic preset, no additional installation is needed.

Installation steps when not using @docusaurus/preset-classic
  1. Install the package:
npm install --save @docusaurus/theme-search-algolia
  1. Register the theme in docusaurus.config.js:
docusaurus.config.js
export default {
  title: 'My site',
  // ...
  themes: ['@docusaurus/theme-search-algolia'],
  themeConfig: {
    // ...
  },
};

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

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    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',

      indexName: 'YOUR_INDEX_NAME',

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

      // Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them.
      externalUrlRegex: 'external\\.com|domain\\.com',

      // Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs
      replaceSearchResultPathname: {
        from: '/docs/', // or as RegExp: /\/docs\//
        to: '/',
      },

      // 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 (`false` by default)
      insights: false,

      //... other Algolia params
    },
  },
};
info

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

Refer to its official DocSearch documentation for possible values.

warning

The search feature will not work reliably until Algolia crawls your site.

If search doesn't work after any significant change, please use the Algolia dashboard to trigger a new crawl.

Contextual search is enabled by default.

It ensures that search results are relevant to the current language and version.

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      contextualSearch: true,
    },
  },
};

Let's consider you have 2 docs versions (v1 and v2) and 2 languages (en and fr).

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

Similarly, when browsing the French site, it would be odd to return search results for the English docs.

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

  • on /en/docs/v1/myDoc, search results will only include English results for the v1 docs (+ other unversioned pages)
  • on /fr/docs/v2/myDoc, search results will only include French results for the v2 docs (+ other unversioned pages)
info

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

For specific needs, you can disable contextualSearch and define your own facetFilters:

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

Refer to the relevant Algolia faceting documentation.

Contextual search doesn't work?

If you only get search results when Contextual Search is disabled, this is very likely because of an index configuration issue.

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
[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);
}

[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
export default {
  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

Troubleshooting​

Here are the most common issues Docusaurus users face when using Algolia DocSearch.

No Search Results​

Seeing no search results is usually related to an index configuration problem.

How to check if I have a config problem?

Docusaurus uses Algolia faceting for its Contextual Search feature, to create dynamic queries such as:

[
  "language:en",
  [
    "docusaurus_tag:default",
    "docusaurus_tag:docs-default-3.2.1",
    "docusaurus_tag:docs-community-current",
    "docusaurus_tag:docs-docs-tests-current"
  ]
]

On the Algolia UI, your index should allow to create facet queries on fields docusaurus_tag, language, lang, version, type, as shown in the screenshot below:

Algolia index showing appropriate faceting fields

Alternatively, if you disable Contextual Search with {contextualSearch: false} (which we don't particularly recommend), Docusaurus will not use facet queries, and you should start seeing results.

Use the recommended configuration

We recommend a specific crawler configuration for a good reason. We cannot support you if you choose to use a different configuration.

You can fix index configuration problems by following those steps:

  1. Use the recommend crawler configuration
  2. Delete your index through the UI
  3. Trigger a new crawl through the UI
  4. Check your index is recreated with the appropriate faceting fields: docusaurus_tag, language, lang, version, type
  5. See that you now get search results, even with Contextual Search enabled

Support​

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

You can reach out to Algolia via their support page 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 an src/theme/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.