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
đ„ 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 toute documentation de développeur ou blog technique : 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.
Par défaut, le preset Docusaurus génÚre un sitemap.xml que le robot d'exploration Algolia peut utiliser.
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.
It is highly recommended to use our official Docusaurus v3 crawler configuration. We cannot support you if you choose a different crawler configuration.
The crawler configuration contains a initialIndexSettings
, which will only be used to initialize your Algolia index if it does not exist yet.
If you update your initialIndexSettings
crawler setting, it is possible to update the index manually through the interface, but the Algolia team recommends to delete your index and then restart a crawl to fully reinitialize it with the new settings.
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
npm install --save @docusaurus/theme-search-algolia
yarn add @docusaurus/theme-search-algolia
pnpm add @docusaurus/theme-search-algolia
- Enregistrez le thĂšme dans
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.
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
},
},
};
L'option searchParameters
a été nommée algoliaOptions
dans Docusaurus v1.
Reportez-vous Ă sa documentation officielle de DocSearch pour les valeurs possibles.
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.
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)
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
:
export default {
// ...
themeConfig: {
// ...
algolia: {
contextualSearch: false,
searchParameters: {
facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
},
},
},
};
Reportez-vous Ă la Documentation sur les facettes d'Algolia correspondante.
If you only get search results when Contextual Search is disabled, this is very likely because of an index configuration issue.
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
.
[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
.
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
npm run swizzle @docusaurus/theme-search-algolia SearchBar
yarn swizzle @docusaurus/theme-search-algolia SearchBar
pnpm 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 an 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:
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.
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:
- Use the recommend crawler configuration
- Delete your index through the UI
- Trigger a new crawl through the UI
- Check your index is recreated with the appropriate faceting fields:
docusaurus_tag
,language
,lang
,version
,type
- See that you now get search results, even with Contextual Search enabled
Supportâ
L'Ă©quipe d'Algolia DocSearch peut vous aider Ă trouver des problĂšmes de recherche sur votre site.
Vous pouvez contacter Algolia via leur page de support 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
npm run swizzle @docusaurus/theme-classic SearchBar
yarn swizzle @docusaurus/theme-classic SearchBar
pnpm run swizzle @docusaurus/theme-classic SearchBar
Ceci va créer un fichier src/theme/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.