Configuration requise

Traduction Bêta Non Officielle

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 →

Cette section, enrichie par les détails sur la construction de notre index DocSearch, vous présente les bonnes pratiques pour optimiser notre crawl. L'adoption de ces spécifications est indispensable pour permettre à notre crawler de créer la meilleure expérience à partir de votre site. Vous devrez modifier votre site et suivre ces règles.

Note : Si votre site est généré avec l'un de nos outils pris en charge, aucune modification n'est nécessaire car il respecte déjà nos exigences.

Exemple de configuration générique

{
  "index_name": "example",
  "start_urls": ["https://www.example.com/doc/"],
  "sitemap_urls": ["https://www.example.com/sitemap.xml"],
  "stop_urls": [],
  "selectors": {
    "lvl0": {
      "selector": ".DocSearch-lvl0",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": {
      "selector": ".DocSearch-lvl1",
      "global": true,
      "default_value": "Chapter"
    },
    "lvl2": ".DocSearch-content .DocSearch-lvl2",
    "lvl3": ".DocSearch-content .DocSearch-lvl3",
    "lvl4": ".DocSearch-content .DocSearch-lvl4",
    "lvl5": ".DocSearch-content .DocSearch-lvl5",
    "lvl6": ".DocSearch-content .DocSearch-lvl6",
    "text": ".DocSearch-content p, .DocSearch-content li"
  },
  "custom_settings": {
    "attributesForFaceting": ["language", "version"]
  },
  "nb_hits": "OUTPUT OF THE CRAWL"
}

Vue d'ensemble d'une structure claire

Un site implémentant ces bonnes pratiques apparaîtra simple et parfaitement clair. Il peut se présenter ainsi :

L'élément bleu principal correspondra à votre conteneur .DocSearch-content. Plus de détails dans les lignes directrices suivantes.

Utilisez les bonnes classes comme sélecteurs

Vous pouvez ajouter des classes statiques spécifiques pour nous aider à identifier le rôle de votre contenu. Ces classes ne doivent pas impacter le style. Ces classes dédiées nous permettront de créer une excellente expérience d'apprentissage au fil de la saisie pour votre documentation.

• Ajoutez une classe statique DocSearch-content au conteneur principal de votre contenu textuel. Généralement, cette balise est un élément HTML <main> ou <article>.

• Tout élément lvl consultable en dehors de ce conteneur principal (par exemple dans une barre latérale) doit être un sélecteur global. Ils seront récupérés globalement et injectés dans chaque enregistrement construit à partir de votre page. Attention : la valeur de niveau est importante et chaque élément correspondant doit avoir un niveau croissant dans le flux HTML. Un niveau X (pour lvlX) doit apparaître après un niveau Y lorsque X > Y.

• Les sélecteurs lvlX doivent utiliser les balises de titre standard comme h1, h2, h3, etc. Vous pouvez aussi utiliser des classes statiques. Attribuez un id ou name unique à ces éléments comme détaillé ci-dessous.

• Tous les éléments DOM correspondant aux sélecteurs lvlX doivent avoir un attribut id ou name unique. Cela aidera la redirection à faire défiler directement jusqu'à l'emplacement exact des éléments correspondants. Ces attributs définissent l'ancre à utiliser.

• Tout élément textuel (sélecteur text) doit être encapsulé dans une balise <p> ou <li>. Ce contenu doit être atomique et divisé en petites entités. Veillez à ne jamais imbriquer un élément correspondant dans un autre pour éviter les doublons.

• Restez cohérent et n'oubliez pas que nous devons maintenir une uniformité dans le flux HTML comme présenté ici.

Intégrez des informations globales via des balises meta

Notre crawler extrait automatiquement les informations de nos balises meta spécifiques à DocSearch :

<meta name="docsearch:language" content="en" />
<meta name="docsearch:version" content="1.0.0" />

Le crawl ajoute la valeur content de ces balises meta à tous les enregistrements extraits de la page. L'attribut name des balises meta doit suivre le modèle docsearch:$NAME. $NAME correspond au nom de l'attribut défini pour tous les enregistrements.

Vous pouvez ensuite transformer ces attributs en facetFilters pour les filtrer depuis l'interface. Vous devrez configurer le paramètre attributesForFaceting de l'index Algolia. Soumettez une PR sur votre configuration associée via le paramètre custom_settings de DocSearch.

"custom_settings": {
  "attributesForFaceting": ["language", "version"]
}

Cela vous permet de filtrer sur la valeur de ces balises meta. L'exemple suivant montre comment mettre à jour l'extrait JavaScript pour récupérer les enregistrements de ces pages.

docsearch({
  […],
  algoliaOptions: {
    'facetFilters': ["language:en", "version:1.0.0"]
  },
  […],
});

La balise meta docsearch:version peut contenir des tokens séparés par des virgules, chacun représentant une version pertinente pour la page. Ces tokens doivent être conformes à la spécification SemVer ou ne contenir que des caractères alphanumériques (ex: latest, next, etc.). En tant que filtres à facettes, ces tokens de version sont insensibles à la casse.

Par exemple, tous les enregistrements extraits d'une page avec la balise meta suivante :

<meta name="docsearch:version" content="2.0.0-alpha.62,latest" />

L'attribut version de ces enregistrements sera :

version:["2.0.0-alpha.62" , "latest"]

Recommandations complémentaires

• Votre site web doit disposer d'un sitemap mis à jour. Ceci est essentiel pour que notre crawler sache quels contenus mettre à jour. Ne vous inquiétez pas, nous continuerons à explorer votre site et à découvrir les hyperliens intégrés pour indexer votre excellent contenu.

• Chaque page doit rendre son contexte complet disponible. L'utilisation d'éléments globaux peut y contribuer (voir ci-dessus).

• Assurez-vous que votre documentation reste accessible sans rendu JavaScript côté client. Si JavaScript est absolument nécessaire, vous devez définir js_render: true dans votre configuration.

Des questions ? Rejoignez-nous sur Discord ou contactez notre équipe support.