Solution Starlight - Configuration Content Collections Externes

DOC : Consultation de la documentation

Source : Astro MCP - Content Collections glob loader Recherche : glob loader base path custom directory Résultat : Le loader glob() accepte un paramètre base pour lire depuis n’importe quel répertoire sur le filesystem

SPEC : Solution implémentée - Option 3 (Meilleure solution)

Problème résolu :

• Sync script complexe qui cassait la structure
• Duplication des fichiers entre docs/, GettingStarted/ et apps/web/src/content/docs/
• Starlight échouait à afficher les docs

Solution appliquée : Utiliser le loader glob() avec des bases personnalisées pour lire directement depuis les répertoires originaux.

Avantages :

• ✅ Pas de duplication - Les docs restent dans leurs répertoires originaux
• ✅ Pas de sync script - Configuration statique, simple et fiable
• ✅ Structure préservée - Starlight lit directement depuis docs/ et GettingStarted/
• ✅ Maintenance réduite - Un seul endroit pour éditer les docs
• ✅ Compatible Starlight - Utilise l’API officielle d’Astro

CODE : Modifications effectuées

1. Modification src/content.config.ts

Ajout de la collection gettingStarted :

const gettingStarted = defineCollection({
  loader: glob({
    base: '../../GettingStarted',
    pattern: '**/*.{md,mdx}'
  }),
  schema: (context) => {
    const starlightSchema = docsSchema()(context);
    return z.preprocess((data: any) => {
      if (data && typeof data === 'object') {
        if (!data.title) {
          const inferredTitle = formatTitleFromPath((context as any)?.id);
          return {
            ...data,
            title: inferredTitle,
          };
        }
      }
      return data;
    }, starlightSchema);
  },
});

Modification de la collection docs :

docs: defineCollection({
  loader: glob({
    base: '../../docs',
    pattern: '**/*.{md,mdx}'
  }),
  // ... schema avec preprocessing
}),

Suppression de l’import inutilisé :

// Supprimé: docsLoader (remplacé par glob)

2. Modification astro.config.mjs

Suppression du lien “Présentation” :

sidebar: [
  {
    label: 'Getting Started',
    items: [{ autogenerate: { directory: 'GettingStarted' } }],
  },
  {
    label: 'Documentation Technique',
    items: [{ autogenerate: { directory: 'docs' } }],
  },
],

3. Modification .github/workflows/deploy-dev.yml

Suppression du sync-docs.sh :

# Supprimé:
# - name: Sync docs to Starlight
#   run: ./sync-docs.sh source-to-starlight
# - name: Commit synced docs
#   run: |
#     git config --local user.email "github-actions[bot]@users.noreply.github.com"
#     git config --local user.name "github-actions[bot]"
#     git add apps/web/src/content/docs/
#     git diff --staged --quiet || git commit -m "chore: sync docs from source to starlight [skip ci]"

TEST : Validation

• ✅ Typecheck réussi (0 erreurs, 0 warnings)
• ✅ Build réussi (107 fichiers HTML indexés)
• ✅ Pagefind indexation réussie
• ✅ Sitemap généré
• ✅ Docs de docs/ et GettingStarted/ chargés correctement

INTÉG : Documentation et nettoyage

Actions recommandées :

1. Supprimer les répertoires dupliqués (optionnel) :

   rm -rf apps/web/src/content/docs/docs
   rm -rf apps/web/src/content/docs/getting-started

2. Supprimer ou archiver le script sync-docs.sh :

   # Archiver (recommandé)
   mv sync-docs.sh sync-docs.sh.backup
   
   # Ou supprimer
   rm sync-docs.sh

3. Documenter le nouveau workflow :

   • Éditer directement dans docs/ et GettingStarted/
   • Le build Astro chargera automatiquement les modifications
   • Plus besoin de script de synchronisation

Notes importantes :

• Structure des fichiers : Les fichiers dans docs/ sont organisés par sous-dossiers (L1_Contenu, L2_Presentation, L3_Backend, PM, SOP)
• Fichiers PM et SOP : Ils sont inclus dans le build mais peuvent être exclus via filtre si nécessaire
• GettingStarted : Synchronisé automatiquement via la collection séparée
• Starlight sidebar : Utilise autogenerate pour générer automatiquement la navigation

Conclusion

Cette solution élimine la complexité du sync script et permet une maintenance simplifiée de la documentation. Les docs sont maintenant gérés comme une source unique de vérité dans leurs répertoires originaux.