Version : 3.0.1

Recherche

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

🥇 Algolia DocSearch (officiel)
👥 Typesense DocSearch
👥 Recherche Locale
👥 Votre propre composant SearchBar

info

🥇 Docusaurus fournit un support de première classe pour Algolia DocSearch.

👥 Les autres options sont maintenues par la communauté : veuillez signaler les bogues dans leurs dépôts respectifs.

🥇 Utiliser Algolia DocSearch

Docusaurus a la prise en charge officielle pour Algolia DocSearch.

Le service est gratuit pour tout projet open-source : il suffit de lire la liste de contrôle et l'appliquer au programme DocSearch.

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.

Si votre site Web est non éligible à la version gratuite hébergée de DocSearch, ou si votre site Web se trouve derrière un pare-feu et qu'il n'est pas publique, vous pouvez exécuter votre propre robot d'exploration DocSearch.

remarque

Par défaut, le preset Docusaurus génère un sitemap.xml que le robot d'exploration Algolia peut utiliser.

Depuis l'ancien docsearch ?

Vous pouvez en savoir plus sur la migration depuis l'ancienne infra DocSearch dans notre article du blog ou les docs de migration DocSearch.

Configuration de l'index

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. La modification et la gestion de vos explorations peuvent être effectuées via l'interface web. 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

Il est fortement recommandé d'utiliser une configuration similaire à la configuration du site web Docusaurus v3.

Connexion à Algolia

Le propre @docusaurus/preset-classic de Docusaurus prend en charge l'intégration de Algolia DocSearch. Si vous utilisez la preset classic, aucune installation supplémentaire n'est nécessaire.

Étapes de l'installation lorsque vous n'utilisez pas @docusaurus/preset-classic

Installez le paquet :

npm
Yarn
pnpm
Bun

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

yarn add @docusaurus/theme-search-algolia

pnpm add @docusaurus/theme-search-algolia

bun add @docusaurus/theme-search-algolia

Enregistrez le thème dans docusaurus.config.js :

docusaurus.config.js
export default {
  title: 'Mon site',
  // ...
  themes: ['@docusaurus/theme-search-algolia'],
  themeConfig: {
    // ...
  },
};

Ensuite, ajoutez un champ algolia dans votre themeConfig. Inscrivez-vous à DocSearch pour obtenir votre index Algolia et votre clé API.

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      // L'ID de l'application fourni par Algolia
      appId: 'YOUR_APP_ID',

      // Clé d'API publique : il est possible de la committer en toute sécurité
      apiKey: 'YOUR_SEARCH_API_KEY',

      indexName: 'YOUR_INDEX_NAME',

      // Facultatif : voir la section doc ci-dessous
      contextualSearch: true,

      // Facultatif : Spécifiez les domaines où la navigation doit se faire par window.location au lieu de history.push. Utile lorsque notre configuration Algolia explore plusieurs sites de documentation et que nous voulons naviguer vers eux avec window.location.href.
      externalUrlRegex: 'external\\.com|domain\\.com',

      // // Facultatif : Remplace certaines parties des URL des éléments d'Algolia. Utile lorsque vous utilisez le même index de recherche pour de multiples déploiements en utilisant une Url de base différente. Vous pouvez utiliser regexp ou string dans le paramètre `from`. Par exemple : localhost:3000 vs myCompany.com/docs
      replaceSearchResultPathname: {
        from: '/docs/', // or as RegExp: /\/docs\//
        to: '/',
      },

      // Facultatif : paramètres de recherche de Algolia
      searchParameters: {},

      // Facultatif : chemin pour la page de recherche qui est activée par défaut (`false` pour le désactiver)
      searchPagePath: 'search',

      // Facultatif : si la fonctionnalité insights est activée ou non sur Docsearch (`false` par défaut)
      insights: false,

      //... autres paramètres de Algolia
    },
  },
};

info

L'option searchParameters a été nommée algoliaOptions dans Docusaurus v1.

Reportez-vous à sa documentation officielle de DocSearch pour les valeurs possibles.

attention

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

Si la recherche ne fonctionne pas après un changement significatif, veuillez utiliser le tableau de bord d'Algolia pour déclencher une nouvelle exploration.

Recherche contextuelle

La recherche contextuelle est activée par défaut.

Elle s'assure que les résultats de recherche sont pertinents pour la langue actuelle et la version.

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

Considérons que vous avez 2 versions de docs (v1 et v2) et 2 langues (en et 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.

sur /en/docs/v1/myDoc, les résultats de recherche n'incluront que les résultats en anglais pour les docs v1 (+ autres pages non versionnées)
sur /fr/docs/v2/myDoc, les résultats de recherche n'incluront que les résultats en français pour les docs v2 (+ autres pages non versionnées)

info

Lors de l'utilisation de contextualSearch: true (par défaut), les filtres de facettes contextuelles seront fusionnés avec ceux fournis avec algolia.searchParameters.facetFilters.

Pour des besoins spécifiques, vous pouvez désactiver contextualSearch et définir vos propres facetFilters :

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

Reportez-vous à la Documentation sur les facettes d'Algolia correspondante.

Styliser votre recherche Algolia

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.

Vous pouvez néanmoins réutiliser les variables CSS Infima de Docusaurus pour styliser DocSearch en modifiant le fichier /src/css/custom.css.

/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%
  );
}

Personnalisation du comportement de la recherche Algolia

Algolia DocSearch prend en charge une liste d'options que vous pouvez passer au champ algolia dans le fichier docusaurus.config.js.

docusaurus.config.js
export default {
  themeConfig: {
    // ...
    algolia: {
      apiKey: 'YOUR_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      // Options...
    },
  },
};

Modifier le composant de recherche Algolia

Si vous préférez modifier le composant React de recherche Algolia, swizzlez le composant SearchBar dans @docusaurus/theme-search-algolia :

npm
Yarn
pnpm
Bun

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

yarn swizzle @docusaurus/theme-search-algolia SearchBar

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

bun 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.

Vous pouvez les contacter par email ou sur Discord.

Docusaurus a également un canal #algolia sur Discord.

👥 Utiliser Typesense DocSearch

Typesense DocSearch fonctionne de manière similaire à Algolia DocSearch, sauf que votre site web est indexé dans un cluster de recherche Typesense.

Typesense est un moteur de recherche instantanée open source que vous pouvez soit :

Auto-héberger sur vos propres serveurs ou
Utilisez le service géré par Typesense Cloud.

Similaire à Algolia DocSearch, il y a deux composants :

typesense-docsearch-scraper - qui balaye votre site Web et indexe les données dans votre cluster Typesense.
docusaurus-theme-search-typesense - un composant d'interface utilisateur de barre de recherche à ajouter à votre site Web.

Lisez la présentation étape par étape pour exécuter typesense-docsearch-scraper et pour installer la barre de recherche dans votre site Docusaurus.

👥 Utiliser la recherche locale

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.

Vous trouverez une liste des plugins de recherche locaux pris en charge par la communauté.

👥 Utiliser votre propre recherche

Pour utiliser votre propre recherche, « swizzlez » le composant SearchBar dans @docusaurus/theme-classic

npm
Yarn
pnpm
Bun

npm run swizzle @docusaurus/theme-classic SearchBar

yarn swizzle @docusaurus/theme-classic SearchBar

pnpm run swizzle @docusaurus/theme-classic SearchBar

bun run swizzle @docusaurus/theme-classic SearchBar

Ceci va créer un fichier src/themes/SearchBar dans le dossier de votre projet. Redémarrez votre serveur de développement et éditez le composant, vous verrez que Docusaurus utilise votre propre composant SearchBar maintenant.

Remarques : Vous pouvez alternativement « swizzlez » depuis Algolia SearchBar et créer votre propre composant de recherche.

🥇 Utiliser Algolia DocSearch​

Configuration de l'index​

Connexion à Algolia​

Recherche contextuelle​

Styliser votre recherche Algolia​

Personnalisation du comportement de la recherche Algolia​

Modifier le composant de recherche Algolia​

Support​

👥 Utiliser Typesense DocSearch​

👥 Utiliser la recherche locale​

👥 Utiliser votre propre recherche​

🥇 Utiliser Algolia DocSearch

Configuration de l'index

Connexion à Algolia

Recherche contextuelle

Styliser votre recherche Algolia

Personnalisation du comportement de la recherche Algolia

Modifier le composant de recherche Algolia

Support

👥 Utiliser Typesense DocSearch

👥 Utiliser la recherche locale

👥 Utiliser votre propre recherche