Skip to content
AMN Docs

Roadmap - Optimisation de l'Intégration Algolia DocSearch

Roadmap - Optimisation de l'Intégration Algolia DocSearch

Plan d'amélioration pas-à-pas de l'intégration Algolia DocSearch pour AMN Docs

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)
  1. 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',
    }
  2. Pousser les records vers l’index via l’API Algolia (Admin API Key)
  3. 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)

  1. Phase 3 : Script d’indexation automatisé

Priorité 3 (Amélioration - Moyen terme)

  1. Phase 4 : Optimisation de la recherche
  2. 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

Historique des Modifications

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

Contents

Built with StarlightPowered by Cloudflare