Guide d'Indexation des Documents dans Algolia DocSearch

Guide d’Indexation Algolia DocSearch pour AMN Docs

Ce guide détaille exactement comment alimenter votre index Algolia amn_docs_dev (App ID: 56TZE3L6C6) afin que les recherches effectuées dans le composant Starlight renvoient immédiatement les résultats de votre documentation.

---

1. Vue d’ensemble du fonctionnement

Algolia fonctionne avec un index de documents JSON stocké dans votre compte Cloud Algolia. Actuellement :

• Le composant frontend est connecté à votre application (App ID: 56TZE3L6C6, Index: amn_docs_dev).
• L’index amn_docs_dev est vide, ce qui explique pourquoi la recherche n’affiche encore aucun résultat sur vos termes.

Pour que la recherche fonctionne, il existe deux méthodes pour remplir votre index Algolia :

---

2. Méthode A : Indexation Automatique via le Robot Algolia Crawler (Pour les pages publiques)

Si votre site est déployé publiquement (ex: sur https://amn-dev.anderson-metsanou.workers.dev) :

1. Connectez-vous à votre tableau de bord dashboard.algolia.com.
2. Dans le menu latéral de gauche, cliquez sur Crawler (ou Data Sources > Crawler).
3. Cliquez sur New Crawler (ou Create Crawler).
4. Renseignez la configuration de base :
   • Start URL : https://amn-dev.anderson-metsanou.workers.dev/
   • Index Name : amn_docs_dev
5. Cliquez sur Start Crawling.
   • Le robot d’Algolia va parcourir le site, extraire le texte des titres (h1, h2), paragraphes et sections, et remplir automatiquement l’index amn_docs_dev.

---

3. Méthode B : Indexation Automatisée via Script Local (Recommandée)

Cette méthode est idéale pour :

• Les documents privées (bloqués derrière le login Better Auth)
• L’environnement local sans URL publique pour le robot
• Le contrôle total sur la structure des hiérarchies et des métadonnées

Étape 1 : Vérifier les variables d’environnement

Les clés Algolia sont déjà configurées dans votre fichier .env :

PUBLIC_ALGOLIA_APP_ID=56TZE3L6C6
PUBLIC_ALGOLIA_SEARCH_API_KEY=9e8bd7effb738f05bd107640cea03013
ALGOLIA_ADMIN_API_KEY=963f4a990dfe892ad6362b4c1c518912
PUBLIC_ALGOLIA_INDEX_NAME=amn_docs_dev

Important : La clé ALGOLIA_ADMIN_API_KEY possède les droits d’écriture sur votre index Algolia. Conservez-la secrète et ne la commitez jamais dans le repository.

Étape 2 : Lancer l’indexation automatisée

Le script apps/web/scripts/index-algolia-docs.ts parcourt tous les fichiers Markdown dans src/content/docs/ et les indexe automatiquement dans Algolia.

task index:algolia

Le script effectue les opérations suivantes :

1. Parcourt récursivement tous les fichiers .md dans src/content/docs/
2. Parse le frontmatter pour extraire le titre du document
3. Parse le contenu Markdown pour extraire les hiérarchies de titres (h1-h6)
4. Génère les records au format DocSearch avec des hiérarchies propres
5. Envoie les records vers l’index amn_docs_dev via l’API Algolia
6. Configure les paramètres de l’index (searchableAttributes, attributesToRetrieve, etc.)

Étape 3 : Structure des records générés

Le script génère des records avec la structure suivante :

{
  "objectID": "0-https://amn-dev.lasommedesrosees.com/docs/...",
  "url": "https://amn-dev.lasommedesrosees.com/docs/...",
  "url_without_anchor": "https://amn-dev.lasommedesrosees.com/docs/...",
  "hierarchy": {
    "lvl0": "Titre du document",
    "lvl1": "Titre h1",
    "lvl2": "Titre h2",
    "lvl3": null,
    "lvl4": null,
    "lvl5": null,
    "lvl6": null
  },
  "content": "Contenu textuel du document...",
  "type": "lvl0"
}

Notes importantes :

• Le script crée un record par niveau de hiérarchie (lvl0 pour la page, lvl1-lvl6 pour les sections)
• Le contenu est tronqué à 5000 caractères pour respecter la limite de 10KB par record d’Algolia
• Les hiérarchies sont basées sur les titres réels des fichiers Markdown, pas sur les chemins de fichiers

---

4. Vérification finale

Une fois l’indexation terminée :

1. Lancez le serveur local avec task dev:wrangler.
2. Ouvrez une page de documentation (ex: http://localhost:8787/gettingstarted/01-setup-local/).
3. Cliquez sur la barre de recherche (Ctrl+K) et saisissez un mot présent dans vos docs (ex: studio, better, cloudflare).
4. Vérifiez que :
   • Les résultats sont pertinents
   • Les hiérarchies s’affichent correctement (sans concaténation de chemins)
   • Cliquer sur un résultat redirige vers le bon document

5. Nettoyage de l’index (si nécessaire)

Si vous devez nettoyer l’index avant de réindexer (par exemple pour supprimer des données du crawler) :

# Vider l'index
npx @algolia/cli indices clear amn_docs_dev -y --application-id 56TZE3L6C6 --api-key 963f4a990dfe892ad6362b4c1c518912

# Réindexer
task index:algolia

6. Dépannage

Les résultats de recherche montrent des hiérarchies concaténées

Cela signifie que l’index contient encore des anciens records du crawler. Videz l’index et réindexez :

npx @algolia/cli indices clear amn_docs_dev -y --application-id 56TZE3L6C6 --api-key 963f4a990dfe892ad6362b4c1c518912
task index:algolia

Les liens de recherche ne redirigent pas vers le bon document

Vérifiez que la variable SITE_URL dans .env correspond à votre URL de déploiement. Pour le développement local, assurez-vous que les liens relatifs fonctionnent correctement.

Erreur “Record is too big”

Le script tronque automatiquement le contenu à 5000 caractères pour respecter la limite de 10KB par record d’Algolia. Si vous rencontrez cette erreur, vérifiez que vos fichiers Markdown ne contiennent pas de sections extrêmement longues.