Version : 2.4.3

Recherche

Il y a quelques options que vous pouvez utiliser pour ajouter une recherche à votre site web :

🥇 Algolia DocSearch (official)
👥 Typesense DocSearch
👥 Local Search
👥 Your own SearchBar component

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 open-source project: just make sure to read the checklist and apply to the DocSearch program.

DocSearch explore votre site web une fois par semaine (le planning est configurable depuis l'interface web) et agrège tout le contenu dans un index Algolia. Ce contenu est ensuite interrogé directement depuis votre front-end en utilisant l'API Algolia.

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.

remarque

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.

Index Configuration

Une fois que votre application a été approuvée et déployée, vous recevrez un e-mail avec tous les détails pour ajouter DocSearch à votre projet. Editing and managing your crawls can be done via the web interface. Les index sont facilement disponibles après le déploiement, de sorte que la configuration manuelle n'est généralement pas nécessaire.

astuce

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

Connecting Algolia

Docusaurus' own @docusaurus/preset-classic supports Algolia DocSearch integration. Si vous utilisez la preset classic, aucune installation supplémentaire n'est nécessaire.

Installation steps when not using @docusaurus/preset-classic

Installez le paquet :

npm
Yarn
pnpm

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

yarn add @docusaurus/theme-search-algolia

pnpm add @docusaurus/theme-search-algolia

docusaurus.config.js
module.exports = {
  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
module.exports = {
  // ...
  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',

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

info

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

Refer to its official DocSearch documentation for possible values.

attention

La fonction de recherche ne fonctionnera pas de manière fiable tant que Algolia n'explorera pas votre site.

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

Contextual search

Contextual search is enabled by default.

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

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    // ...
    algolia: {
      contextualSearch: true,
    },
  },
};

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

Lorsque vous parcourez la documentation v2, il serait étrange de retourner les résultats de recherche de la documentation v1. Parfois, les docs v1 et v2 sont assez semblables, et vous vous retrouveriez avec des résultats de recherche en double pour la même requête (un résultat par version).

De même, lorsque vous naviguez sur le site en français, il serait étrange de retourner les résultats de recherche pour la documentation en anglais.

Pour résoudre ce problème, la fonction de recherche contextuelle comprend que vous parcourez une version spécifique et une langue de la documentation et crée les filtres de la requête de recherche de manière dynamique.

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
module.exports = {
  // ...
  themeConfig: {
    // ...
    algolia: {
      contextualSearch: false,
      searchParameters: {
        facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
      },
    },
  },
};

Refer to the relevant Algolia faceting documentation.

Styling your Algolia search

Par défaut, DocSearch est livré avec un thème raffiné qui a été conçu pour l'accessibilité, en veillant à ce que les couleurs et les contrastes respectent les normes.

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
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
Yarn
pnpm

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

yarn swizzle @docusaurus/theme-search-algolia SearchBar

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

Support

L'équipe d'Algolia DocSearch peut vous aider à trouver des problèmes de recherche sur votre 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:

Self-Host on your own servers or
Use the Managed Typesense Cloud service.

Similaire à Algolia DocSearch, il y a deux composants :

typesense-docsearch-scraper - which scrapes your website and indexes the data in your Typesense cluster.
docusaurus-theme-search-typesense - a search bar UI component to add to your website.

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.

👥 Using Local Search

Vous pouvez utiliser un plugin de recherche locale pour les sites Web où l'index de recherche est de petite taille et peut être téléchargé dans le navigateur de vos utilisateurs lorsqu'ils visitent votre site Web.

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

👥 Using your own search

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

npm
Yarn
pnpm

npm run swizzle @docusaurus/theme-classic SearchBar

yarn swizzle @docusaurus/theme-classic SearchBar

pnpm run swizzle @docusaurus/theme-classic SearchBar

This will create an 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.

Recherche

🥇 Using Algolia DocSearch​

Index Configuration​

Connecting Algolia​

Contextual search​

Styling your Algolia search​

Customizing the Algolia search behavior​

Editing the Algolia search component​

Support​

👥 Using Typesense DocSearch​

👥 Using Local Search​

👥 Using your own search​

🥇 Using Algolia DocSearch

Index Configuration

Connecting Algolia

Contextual search

Styling your Algolia search

Customizing the Algolia search behavior

Editing the Algolia search component

Support

👥 Using Typesense DocSearch

👥 Using Local Search

👥 Using your own search