Fichiers de configuration
Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →
Un fichier DocSearch ressemble à ceci :
{
"index_name": "example",
"start_urls": ["https://www.example.com/docs"],
"selectors": {
"lvl0": "#content header h1",
"lvl1": "#content article h1",
"lvl2": "#content section h3",
"lvl3": "#content section h4",
"lvl4": "#content section h5",
"lvl5": "#content section h6",
"text": "#content header p,#content section p,#content section ol"
}
}
index_name
Il s'agit du nom de l'index Algolia où vos enregistrements seront envoyés. La clé apiKey que nous vous partagerons est restreinte à cet index et est une clé de recherche uniquement.
Avec le crawler DocSearch gratuit, le indexName correspond toujours au nom du fichier de configuration. Si vous exécutez DocSearch vous-même, vous pouvez choisir n'importe quel nom.
{
"index_name": "example"
}
Lors de son exécution, le scraper DocSearch construit un index temporaire. Une fois le scraping terminé, il remplace l'index existant par cet index temporaire en utilisant le nom spécifié dans index_name.
Par défaut, le nom de l'index temporaire est la valeur de index_name + _tmp.
Pour utiliser un nom différent, définissez la variable d'environnement INDEX_NAME_TMP. Cette variable peut être configurée dans le fichier .env aux côtés de APPLICATION_ID et API_KEY.
start_urls
Ce tableau contient la liste des URL de départ pour le crawl de votre site. Le crawler suivra récursivement tous les liens (<a>) à partir de ces pages. Il ignore les liens vers d'autres domaines et les URL correspondant à stop_urls.
{
"start_urls": ["https://www.example.com/docs"]
}
selectors_key, personnaliser vos sélecteurs
Vous pouvez définir des ensembles de sélecteurs plus précis selon l'URL en utilisant le paramètre selectors_key dans vos start_urls.
{
"start_urls": [
{
"url": "http://www.example.com/docs/faq/",
"selectors_key": "faq"
},
{
"url": "http://www.example.com/docs/"
}
],
[…],
"selectors": {
"default": {
"lvl0": ".docs h1",
"lvl1": ".docs h2",
"lvl2": ".docs h3",
"lvl3": ".docs h4",
"lvl4": ".docs h5",
"text": ".docs p, .docs li"
},
"faq": {
"lvl0": ".faq h1",
"lvl1": ".faq h2",
"lvl2": ".faq h3",
"lvl3": ".faq h4",
"lvl4": ".faq h5",
"text": ".faq p, .faq li"
}
}
}
Pour déterminer le sous-ensemble à appliquer, le scraper parcourt les éléments de start_urls et applique uniquement le premier qui correspond à l'URL.
Prenons l'URL http://www.example.com/en/api/ avec cette configuration :
{
"start_urls": [
{
"url": "http://www.example.com/doc/",
"selectors_key": "doc"
},
{
"url": "http://www.example.com/doc/faq/",
"selectors_key": "faq"
},
[…],
]
}
Seul l'ensemble de sélecteurs lié à doc sera appliqué à l'URL. La configuration correcte doit être construite dans l'ordre inverse (comme initialement décrit).
Si un élément de start_urls n'a pas de selectors_key, c'est l'ensemble default qui sera utilisé. N'oubliez pas de définir ce jeu de secours.
Utilisation d'expressions régulières
Les options start_urls et stop_urls acceptent des expressions régulières pour des motifs complexes. Vous pouvez utiliser soit un tableau d'expressions, soit un objet contenant au minimum une clé url pointant vers une page accessible.
Avec la syntaxe objet, vous pouvez ajouter une clé variables injectée dans votre motif d'URL. L'exemple suivant illustre cette fonctionnalité :
{
"start_urls": [
{
"url": "http://www.example.com/docs/(?P<lang>.*?)/(?P<version>.*?)/",
"variables": {
"lang": ["en", "fr"],
"version": ["latest", "3.3", "3.2"]
}
}
]
}
L'effet secondaire bénéfique : chaque enregistrement extrait des pages correspondant à http://www.example.com/docs/en/latest aura les attributs lang: en et version: latest. Cela permet un filtrage via facetFilters.
L'exemple suivant montre comment l'interface filtre les résultats par langue et version.
docsearch({
[…],
algoliaOptions: {
'facetFilters': ["lang:en", "version:latest"]
},
[…],
});
Utilisation de tags personnalisés
Vous pouvez appliquer des tags personnalisés à certaines pages sans expressions régulières. Ajoutez-les via la clé tags. Ces tags deviendront automatiquement des facettes dans Algolia, permettant un filtrage par leurs valeurs.
{
"start_urls": [
{
"url": "http://www.example.com/docs/concepts/",
"tags": ["concepts", "terminology"]
}
]
}
Depuis l'extrait JS :
docsearch({
[…],
algoliaOptions: {
'facetFilters': ["tags:concepts"]
},
});
Utilisation du Page Rank
Pour accorder plus de poids à certaines pages. Ce paramètre booste les enregistrements issus de la page. Les pages avec un page_rank plus élevé seront retournées avant celles avec un page_rank plus bas. Les valeurs numériques (négatives incluses) sont acceptées.
{
"start_urls": [
{
"url": "http://www.example.com/docs/concepts/",
"page_rank": 5
},
{
"url": "http://www.example.com/docs/contributors/",
"page_rank": 1
}
]
}
Dans cet exemple, les résultats de la page Concepts auront un rang supérieur à ceux de la page Contributeurs.
Utilisation de sélecteurs personnalisés par page
Si le balisage de votre site web varie considérablement d'une page à l'autre, rendant impossible l'utilisation de sélecteurs génériques, vous pouvez organiser vos sélecteurs par espaces de noms et spécifier quel ensemble doit s'appliquer à des pages particulières.
{
"start_urls": [
"http://www.example.com/docs/",
{
"url": "http://www.example.com/docs/concepts/",
"selectors_key": "concepts"
},
{
"url": "http://www.example.com/docs/contributors/",
"selectors_key": "contributors"
}
],
"selectors": {
"default": {
"lvl0": ".main h1",
"lvl1": ".main h2",
"lvl2": ".main h3",
"lvl3": ".main h4",
"lvl4": ".main h5",
"text": ".main p"
},
"concepts": {
"lvl0": ".header h2",
"lvl1": ".main h1.title",
"lvl2": ".main h2.title",
"lvl3": ".main h3.title",
"lvl4": ".main h5.title",
"text": ".main p"
},
"contributors": {
"lvl0": ".main h1",
"lvl1": ".contributors .name",
"lvl2": ".contributors .title",
"text": ".contributors .description"
}
}
}
Dans cet exemple, toutes les pages de documentation utiliseront les sélecteurs définis dans selectors.default, tandis que les pages sous ./concepts utiliseront selectors.concepts et celles sous ./contributors utiliseront selectors.contributors.
selectors
Cet objet contient tous les sélecteurs CSS utilisés pour créer la hiérarchie des enregistrements. Il peut inclure jusqu'à 6 niveaux (lvl0, lvl1, lvl2, lvl3, lvl4, lvl5) et text.
Une configuration typique ciblerait le title ou h1 de la page comme lvl0, les h2 comme lvl1, les h3 comme lvl2, et les p comme text, mais cela dépend entièrement de votre structure HTML.
La clé text est obligatoire, mais nous recommandons vivement de définir aussi lvl0, lvl1 et lvl2 pour obtenir une pertinence optimale.
{
"selectors": {
"lvl0": "#content header h1",
"lvl1": "#content article h1",
"lvl2": "#content section h3",
"lvl3": "#content section h4",
"lvl4": "#content section h5",
"lvl5": "#content section h6",
"text": "#content header p,#content section p,#content section ol"
}
}
Les sélecteurs peuvent être transmis sous forme de chaînes ou d'objets contenant une clé selector. D'autres clés spéciales peuvent être définies comme expliqué ci-dessous.
{
"selectors": {
"lvl0": {
"selector": "#content header h1"
}
}
}
Utilisation de sélecteurs globaux
L'approche par défaut d'extraction de contenu via les sélecteurs consiste à lire le balisage HTML de haut en bas. Cela fonctionne bien avec du contenu semi-structuré comme une hiérarchie d'en-têtes, mais échoue lorsque les informations pertinentes ne font pas partie du même flux (par exemple un titre hors en-tête ou sidebar).
Dans ce cas, vous pouvez définir un sélecteur comme global : il s'appliquera à toute la page et sera identique pour tous les enregistrements extraits.
{
"selectors": {
"lvl0": {
"selector": "#content header h1",
"global": true
}
}
}
Nous déconseillons d'utiliser des sélecteurs text globaux.
Définition d'une valeur par défaut
Si un sélecteur ne trouve aucun élément valide sur la page, vous pouvez définir une default_value comme valeur de repli.
{
"selectors": {
"lvl0": {
"selector": "#content header h1",
"default_value": "Documentation"
}
}
}
Suppression des caractères superflus
Certaines documentations ajoutent des caractères spéciaux aux titres (#, ›, etc.). Ces éléments ont une valeur stylistique mais pas sémantique, et ne devraient pas être indexés.
Définissez une liste de caractères à exclure de la valeur indexée finale via la clé strip_chars.
{
"selectors": {
"lvl0": {
"selector": "#content header h1",
"strip_chars": "#›"
}
}
}
Notez que vous pouvez aussi définir strip_chars à la racine de la configuration pour l'appliquer à tous les sélecteurs.
{
"strip_chars": "#›"
}
Ciblage d'éléments avec XPath
Les sélecteurs CSS sont un moyen clair et concis de cibler les éléments d'une page, mais ils présentent des limitations. Par exemple, vous ne pouvez pas remonter la cascade avec CSS.
Si vous avez besoin d'un mécanisme de sélecteurs plus puissant, vous pouvez les écrire en XPath en définissant type: xpath.
L'exemple suivant recherche un li.chapter.active.done, remonte de deux niveaux dans le DOM pour trouver un a, et utilise le contenu de cet a comme valeur du sélecteur lvl0.
{
"selectors": {
"lvl0": {
"selector": "//li[@class=\"chapter active done\"]/../../a",
"type": "xpath",
"global": true
}
}
}
Les sélecteurs XPath peuvent être complexes à lire. Testez-les systématiquement dans votre navigateur pour vérifier qu'ils ciblent bien les éléments attendus.
custom_settings Optionnel
Cette clé permet de surcharger les paramètres de votre index Algolia. Nous déconseillons de les modifier car les réglages par défaut conviennent à la plupart des sites.
custom_settings.separatorsToIndexOptionnel
Un cas d'usage typique est la configuration de separatorsToIndex. Par défaut, Algolia considère tous les caractères spéciaux comme séparateurs. Pour des contextes comme des noms de méthodes, vous pourriez vouloir préserver la signification de _, / ou #.
{
"custom_settings": {
"separatorsToIndex": "_/"
}
}
Consultez la documentation Algolia pour plus de détails sur les paramètres.
custom_settings.synonyms Facultatif
custom_settings peut inclure une clé synonyms qui est un tableau de synonymes. Chaque élément est un tableau de synonymes à un mot. Ces mots sont interchangeables.
Par exemple :
"custom_settings": {
"synonyms": [
[
"js",
"javascript"
],
[
"es6",
"ECMAScript6",
"ECMAScript2015"
]
]
},
Notez que vous pouvez utiliser des synonymes avancés avec Algolia. Notre scraper ne prend en charge que les synonymes réguliers à un mot.
scrape_start_urls Facultatif
Par défaut, le crawler extraira le contenu des pages définies dans start_urls. Si vous n'avez pas de contenu pertinent sur vos starts_urls ou s'il s'agit d'un doublon d'une autre page, définissez ce paramètre sur false.
{
"scrape_start_urls": false
}
selectors_exclude Facultatif
Ce paramètre attend un tableau de sélecteurs CSS. Tout élément correspondant à l'un de ces sélecteurs sera supprimé de la page avant toute extraction de données.
Cela permet de supprimer une table des matières, une barre latérale ou un pied de page pour faciliter l'écriture des autres sélecteurs.
{
"selectors_exclude": [".footer", "ul.deprecated"]
}
stop_urls Facultatif
Il s'agit d'un tableau de chaînes ou d'expressions régulières. Lorsque le crawler s'apprête à visiter un lien, il vérifie d'abord s'il correspond à un élément du tableau. Si c'est le cas, il ne suivra pas le lien. Utilisez ceci pour restreindre les pages accessibles au crawler.
Ce paramètre est souvent utilisé pour éviter les contenus dupliqués, par exemple en ajoutant http://www.example.com/docs/index.html si vous avez déjà http://www.example.com/docs/ dans vos start_urls.
{
"stop_urls": ["https://www.example.com/docs/index.html", "license.html"]
}
min_indexed_level Facultatif
La valeur par défaut est 0. En augmentant cette valeur, vous pouvez choisir de ne pas indexer certains enregistrements s'ils n'ont pas suffisamment de correspondances lvlX. Par exemple, avec min_indexed_level: 2, le scraper indexe uniquement les enregistrements temporaires ayant au moins lvl0, lvl1 et lvl2 définis. Plus de détails sur cette stratégie sont disponibles dans cette section.
C'est utile lorsque votre documentation comporte des pages partageant le même lvl0 et lvl1. Dans ce cas, vous ne voulez pas indexer tous les enregistrements partagés mais conserver des contenus différents entre les pages.
{
"min_indexed_level": 2
}
only_content_level Facultatif
Lorsque only_content_level est défini sur true, le crawler ne créera pas d'enregistrements pour les sélecteurs lvlX.
Dans ce cas, min_indexed_level est ignoré.
{
"only_content_level": true
}
nb_hits Spécial
Nombre d'enregistrements extraits et indexés par DocSearch. Nous vérifions cette clé en interne pour détecter toute variation anormale révélant une mauvaise configuration.
nb_hits est mis à jour automatiquement à chaque exécution de DocSearch. Si le terminal est interactif (tty), DocSearch demandera confirmation avant la mise à jour. Pour éviter cette confirmation, définissez la variable d'environnement UPDATE_NB_HITS à true (activation) ou false (désactivation) dans le fichier .env aux côtés de APPLICATION_ID et API_KEY.
Vous n'avez pas à modifier ce champ. Nous le documentons ici pour votre information.
Sitemaps
Si votre site dispose d'un fichier sitemap.xml, DocSearch peut l'utiliser pour déterminer les pages à crawler.
sitemap_urls Facultatif
Vous pouvez fournir un tableau d'URL pointant vers vos fichiers sitemap. Si ce paramètre est défini, DocSearch lira les URL depuis vos sitemaps au lieu de suivre tous les liens de vos starts_urls.
{
"sitemap_urls": ["http://www.example.com/docs/sitemap.xml"]
}
Vous devez définir explicitement ce paramètre : notre scraper ne suit pas robots.txt.
sitemap_alternate_links Facultatif
Les sitemaps peuvent contenir des liens alternatifs pour les URLs. Il s'agit d'autres versions de la même page, dans une langue différente ou avec une URL distincte. Par défaut, DocSearch ignorera ces URLs.
Définissez cette option sur true si vous souhaitez que ces autres versions soient également explorées.
{
"sitemap_urls": ["http://www.example.com/docs/sitemap.xml"],
"sitemap_alternate_links": true
}
Avec la configuration ci-dessus et le sitemap.xml ci-dessous, les URLs http://www.example.com/docs/ et http://www.example.com/docs/de/ seront toutes deux explorées.
<url>
<loc>http://www.example.com/docs/</loc>
<xhtml:link rel="alternate" hreflang="de" href="http://www.example.com/de/"/>
</url>
Rendu JavaScript
Par défaut, DocSearch suppose que les sites web utilisent le rendu côté serveur, ce qui signifie que le code HTML est directement renvoyé par le serveur. Si votre contenu est généré côté client, vous devez indiquer à DocSearch d'émuler un navigateur via Selenium.
Comme l'exploration côté client est nettement plus lente que côté serveur, nous vous encourageons vivement à mettre à jour votre site pour activer le rendu côté serveur.
js_render Optionnel
Définissez cette valeur sur true si votre site web nécessite un rendu côté client. Cela fera démarrer un proxy Selenium pour récupérer toutes vos pages web.
{
"js_render": true
}
js_wait Optionnel
Si votre site web est lent à charger, vous pouvez utiliser js_wait pour indiquer à DocSearch d'attendre un délai spécifique (en secondes) avant d'extraire le contenu de la page.
Notez que cette option peut considérablement augmenter le temps d'exploration de votre site, et nous vous recommandons plutôt d'activer le rendu côté serveur.
Cette option n'a aucun effet si js_render est défini sur false.
{
"js_render": true,
"js_wait": 2
}
use_anchors Optionnel
Les sites web utilisant le rendu côté client n'emploient souvent pas des URLs complètes, mais exploitent plutôt le fragment d'URL (la partie après le #).
Si votre site web utilise de telles URLs, vous devez définir use_anchors sur true pour que DocSearch indexe tout votre contenu.
{
"js_render": true,
"use_anchors": true
}
user_agent Optionnel
Vous pouvez remplacer l'agent utilisateur employé pour explorer votre site web. Par défaut, cette valeur est :
Algolia DocSearch Crawler
Cependant, si l'exploration de votre site nécessite une émulation de navigateur (c'est-à-dire js_render=true), notre user_agent est :
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/71.0.3578.98 Safari/537.36
Pour le remplacer, dans la configuration :
{
"user_agent": "Custom Bot"
}