Roadmap - Optimisation de l'Intégration Algolia DocSearch

Roadmap : Optimisation de l’Intégration Algolia DocSearch

Contexte

L’intégration Algolia DocSearch est fonctionnelle mais présente plusieurs problèmes identifiés :

• Incohérences de configuration (credentials, index name)
• Problèmes d’affichage des résultats (titres longs, non formatés)
• Manque de configuration avancée (transformItems, searchParameters)
• Absence de script d’indexation automatisé pour les docs privées

Cette roadmap suit le cycle DOC → SPEC → CODE → TEST → INTÉG pour chaque phase.

---

Phase 1 : Correction de la Configuration (DOC → SPEC → CODE)

Objectif

Normaliser les variables d’environnement et corriger les incohérences de configuration.

Étapes

1.1 DOC - Analyse de l’état actuel ✅

• Identifier les incohérences dans .env.example
• Identifier les incohérences dans astro.config.mjs
• Documenter les problèmes dans ce fichier

1.2 SPEC - Spécification des corrections

Variables à normaliser :

# .env.example - CORRECTED
ALGOLIA_APP_ID=56TZE3L6C6
ALGOLIA_SEARCH_API_KEY=9e8bd7effb738f05bd107640cea03013
ALGOLIA_ADMIN_API_KEY=your_admin_api_key_here
ALGOLIA_INDEX_NAME=amn_docs_dev

Modifications dans astro.config.mjs :

• Supprimer les valeurs par défaut hardcodées
• Utiliser uniquement les variables d’environnement
• Ajouter ALGOLIA_ADMIN_API_KEY pour l’indexation

1.3 CODE - Implémentation

Fichiers à modifier :

• .env.example : Corriger les variables Algolia
• apps/web/astro.config.mjs : Supprimer les fallbacks hardcodés

1.4 TEST - Validation

• Vérifier que les variables sont correctement chargées
• Tester que le build fonctionne avec les nouvelles variables
• Vérifier que la recherche fonctionne en local

1.5 INTÉG - Documentation

• Mettre à jour GettingStarted/34-starlight-algolia-docsearch-integration.md
• Mettre à jour GettingStarted/35-algolia-indexing-guide.md

---

Phase 2 : Configuration Avancée DocSearch (DOC → SPEC → CODE)

Objectif

Créer une configuration DocSearch avancée avec transformation des résultats et optimisation des paramètres de recherche.

Étapes

2.1 DOC - Recherche des meilleures pratiques ✅

• Consulter la documentation officielle @astrojs/starlight-docsearch
• Consulter la documentation Algolia DocSearch sur transformItems()
• Consulter la documentation sur searchParameters
• Analyser les exemples de configuration

2.2 SPEC - Spécification de la configuration ✅

Fichier à créer : apps/web/src/config/docsearch.ts

Configuration requise :

• transformItems() : Formatter les titres et hiérarchies
• searchParameters : Optimiser les attributs récupérés
• maxResultsPerGroup : Limiter à 5 résultats par groupe
• insights : Activer pour analytics
• disableUserPersonalization : Conserver à false

Attributs à récupérer :

attributesToRetrieve: [
  'hierarchy.lvl0',
  'hierarchy.lvl1',
  'hierarchy.lvl2',
  'hierarchy.lvl3',
  'content',
  'type',
  'url',
]

2.3 CODE - Implémentation ✅

Fichiers à créer/modifier :

• apps/web/src/config/docsearch.ts : Configuration DocSearch avancée
• apps/web/astro.config.mjs : Remplacer la configuration inline par clientOptionsModule

2.4 TEST - Validation ✅

• Typecheck : task typecheck (0 erreurs, 0 warnings)
• Build : task build:web (25.93s)
• Test local : task dev:wrangler (à faire par l’utilisateur)
• Vérifier que le modal de recherche s’affiche (à faire par l’utilisateur)
• Tester une recherche et vérifier le formatting des résultats (à faire par l’utilisateur)

2.5 INTÉG - Documentation ✅

• Documenter la configuration dans GettingStarted/34-starlight-algolia-docsearch-integration.md
• Expliquer comment personnaliser transformItems()

---

Phase 3 : Script d’Indexation Automatisé (DOC → SPEC → CODE)

Objectif

Créer un script d’indexation local pour alimenter l’index Algolia avec les documents Markdown, y compris les docs privées.

Étapes

3.1 DOC - Analyse des besoins

• Analyser la structure des fichiers Markdown dans src/content/docs/
• Étudier le format des records Algolia DocSearch
• Consulter la documentation sur l’API Algolia pour l’indexation
• Rechercher les meilleures pratiques pour l’indexation de documentation

3.2 SPEC - Spécification du script

Fichier à créer : apps/web/scripts/index-algolia-docs.ts

Fonctionnalités requises :

1. Parcourir récursivement les fichiers .md dans src/content/docs/
2. Parser le frontmatter et le contenu Markdown
3. Extraire la hiérarchie des titres (h1, h2, h3, h4, h5, h6)
4. Générer les records au format DocSearch :

   {
     objectID: string,
     url: string,
     hierarchy: {
       lvl0: string,
       lvl1: string,
       lvl2: string,
       lvl3: string,
       lvl4: string,
       lvl5: string,
       lvl6: string,
     },
     content: string,
     type: 'content' | 'lvl0' | 'lvl1' | 'lvl2' | 'lvl3' | 'lvl4' | 'lvl5' | 'lvl6',
   }

5. Pousser les records vers l’index via l’API Algolia (Admin API Key)
6. Gérer les mises à jour (delta ou full reindex)

Dépendances :

• algoliasearch (client Algolia)
• gray-matter (parser frontmatter)
• markdown-it ou remark (parser Markdown)

3.3 CODE - Implémentation

Fichiers à créer/modifier :

• apps/web/scripts/index-algolia-docs.ts : Script d’indexation
• apps/web/package.json : Ajouter les dépendances nécessaires
• Taskfile.yaml : Ajouter une task index:algolia

3.4 TEST - Validation

• Tester le script sur un petit subset de documents
• Vérifier que les records sont correctement formatés
• Vérifier que l’index est correctement alimenté
• Tester la recherche sur les documents indexés
• Vérifier que les hiérarchies sont correctes

3.5 INTÉG - Intégration dans le workflow

• Ajouter la task index:algolia au Taskfile
• Configurer l’exécution automatique après le build (optionnel)
• Documenter l’utilisation dans GettingStarted/35-algolia-indexing-guide.md
• Configurer pour le CI/CD (si nécessaire)

---

Phase 4 : Optimisation de la Recherche (DOC → SPEC → CODE)

Objectif

Optimiser les settings d’index Algolia pour améliorer la pertinence des résultats.

Étapes

4.1 DOC - Analyse des besoins

• Consulter la documentation Algolia sur searchableAttributes
• Consulter la documentation sur customRanking
• Consulter la documentation sur attributesForFaceting
• Analyser les requêtes de recherche les plus courantes

4.2 SPEC - Spécification des settings

Configuration via Algolia Dashboard ou CLI :

searchableAttributes (ordonnés par importance) :

[
  "unordered(hierarchy.lvl0)",
  "unordered(hierarchy.lvl1)",
  "unordered(hierarchy.lvl2)",
  "unordered(hierarchy.lvl3)",
  "unordered(hierarchy.lvl4)",
  "unordered(hierarchy.lvl5)",
  "unordered(hierarchy.lvl6)",
  "content"
]

customRanking (si applicable) :

[
  "desc(popularity)",
  "desc(updated_at)"
]

attributesForFaceting (si nécessaire) :

[
  "filterOnly(type)",
  "filterOnly(hierarchy.lvl0)"
]

4.3 CODE - Implémentation

Outils à utiliser :

• Algolia Dashboard (interface web)
• Algolia CLI (scriptable)
• Script de configuration (si nécessaire)

4.4 TEST - Validation

• Tester les recherches avec différents termes
• Vérifier la pertinence des résultats
• Tester les filtres (si configurés)
• Vérifier que le ranking fonctionne correctement

4.5 INTÉG - Documentation

• Documenter les settings dans GettingStarted/35-algolia-indexing-guide.md
• Expliquer comment ajuster les settings

---

Phase 5 : Tests Finaux et Validation (TEST → INTÉG)

Objectif

Valider l’ensemble de l’intégration et s’assurer que tout fonctionne correctement.

Étapes

5.1 TEST - Tests complets

• Typecheck : task typecheck
• Lint : task lint
• Build : task build:web
• Test local : task dev:wrangler
• Indexation : task index:algolia
• Tests de recherche avec différents termes
• Tests sur mobile (responsive)
• Tests avec Better Auth (docs privées)

5.2 INTÉG - Documentation finale

• Mettre à jour tous les guides GettingStarted
• Créer un guide de dépannage
• Documenter les bonnes pratiques
• Mettre à jour la checklist de validation

---

Priorités d’Exécution

Priorité 1 (Critique - Immédiat)

1. Phase 1 : Correction de la configuration
2. Phase 2 : Configuration avancée DocSearch

Priorité 2 (Importante - Court terme)

3. Phase 3 : Script d’indexation automatisé

Priorité 3 (Amélioration - Moyen terme)

4. Phase 4 : Optimisation de la recherche
5. Phase 5 : Tests finaux et validation

---

Critères de Succès

Fonctionnels

• La recherche fonctionne correctement
• Les résultats sont pertinents
• Les titres sont bien formatés
• Les hiérarchies sont claires
• L’indexation fonctionne automatiquement

Techniques

• Typecheck passe sans erreurs
• Build passe sans erreurs
• Lint passe sans erreurs
• Tests passent

Expérience Utilisateur

• La recherche est rapide
• L’interface est responsive
• Les résultats sont lisibles
• Les suggestions sont utiles

---

Notes et Décisions

À valider avant de commencer

1. Nom de l’index : amn_docs_dev est-il correct pour l’environnement de développement ?
2. Credentials : Les credentials dans .env sont-ils corrects ?
3. Stratégie d’indexation :
   • A) Crawler Algolia (docs publiques uniquement)
   • B) Script local (tous les docs)
   • C) Les deux

Dépendances externes

• Documentation Algolia DocSearch : https://docsearch.algolia.com/
• Documentation @astrojs/starlight-docsearch : https://starlight.astro.build/guides/site-search/
• Documentation Algolia Search API : https://www.algolia.com/doc/api-reference/search-api-parameters/

---

Historique des Modifications

Date	Version	Description	Auteur
2026-10-06	1.0	Création initiale de la roadmap	Devin