Aller au contenu principal
Version: 2.0.0-beta.7

Recherche

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

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 dans la plupart des cas : il suffit de s'inscrire au programme DocSearch.

Il travaille en explorant le contenu de votre site Web toutes les 24 heures et en mettant 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.

Configuration de l'index

Après avoir appliqué, la config DocSearch de votre site devrait être créée à l'endroit suivant :

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

Ce fichier de configuration peut être mis à jour par :

caution

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

Connexion à Algolia

Le propre @docusaurus/preset-classic de Docusaurus prend en charge une intégration de Algolia DocSearch.

Pour connecter vos docs à Algolia, ajoutez d'abord le package à votre site web :

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

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

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    // ...
    algolia: {
      // Si Algolia ne vous a pas fourni d'appId, utilisez 'BH4D9OD16A'.
      appId: 'YOUR_APP_ID',

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

      indexName: 'YOUR_INDEX_NAME',

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

      // Facultatif : voir la section doc ci-dessous
      appId: 'YOUR_APP_ID',

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

      //... autres paramètres d'Algolia
    },
  },
};
info

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

caution

La fonction de recherche ne fonctionnera pas de manière fiable tant qu'Algolia n'aura pas exploré votre site avec le plugin de recherche activé.

Si vous installez le plugin Algolia pour la première fois et que vous voulez vous assurer que la fonction de recherche fonctionne avant de la déployer en production, vous pouvez demander à l'équipe DocSearch de déclencher un crawl sur une url d'un environnement d'essai ou un aperçu du déploiement.

La recherche contextuelle est principalement utile pour les sites Docusaurus versionnés.

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

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

  • navigation dans /docs/v1/myDoc, les résultats de recherche n'incluront que les docs v1 (+ autres pages non versionnées)
  • navigation dans /docs/v2/myDoc, les résultats de recherche n'incluront que les docs v2 (+ autres pages non versionnées)
docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    // ...
    algolia: {
      contextualSearch: true,
    },
  },
};
caution

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

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

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
module.exports = {
  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 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 :

Similaire à Algolia DocSearch, il y a deux composants :

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

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é listés ici.

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

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