Aller au contenu principal
Version: 2.0.0-beta.7 🚧

Recherche

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

Il existe deux options principales, vous pouvez utiliser Algolia DocSearch ou apporter votre propre composant SearchBar.

Utiliser Algolia DocSearch#

Algolia DocSearch 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. Notez que votre site Web doit être accessible au public pour que cela fonctionne (c'est-à-dire qu'il ne doit pas se trouver derrière un pare-feu). Le service est gratuit.

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, vous pouvez exécuter votre propre robot d'exploration DocSearch. Pour de meilleurs résultats, vous pouvez utiliser un fichier de configuration basé sur la config Docusaurus 2.

Connexion à Algolia#

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: {      apiKey: 'YOUR_API_KEY',      indexName: 'YOUR_INDEX_NAME',
      // Facultatif : voir la section de doc ci-dessous      contextualSearch: true,
      // Facultatif : voir la section de doc ci-dessous      appId: 'YOUR_APP_ID',
      // Facultatif : voir la section de doc ci-dessous      searchParameters: {},
      //... autres paramètres Algolia    },  },};
info

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

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.

ID de l'application personnalisée#

Lorsque vous exécutez votre propre robot d'exploration DocSearch, il est nécessaire de définir la clé de configuration appId à l'ID de votre propre application. S'il n'est pas défini, le appId se rabattra sur celui utilisé avec la version gratuite et hébergée de Algolia DocSearch.

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

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

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.