Plan d'intégration — Starlight Giscus

Plan d’Intégration — Plugin starlight-giscus

Document de Référence : GettingStarted/39-plan-starlight-giscus-integration.md
Source Clonée : ~/astro/starlight-giscus (packages/starlight-giscus@1.2.0)
Version cible : starlight-giscus@1.2.0
Compatibilité : @astrojs/starlight@0.42.4 (peerDependency : >=0.41.0)
Méthodologie : Cycle DOC → SPEC → CODE → TEST → INTÉG

---

1. Synthèse de l’Investigation

L’analyse du code source cloné dans ~/astro/starlight-giscus révèle :

1.1 Architecture du Plugin

• Mécanisme d’injection : Le plugin surcharge le composant Pagination via starlight-giscus/overrides/Pagination.astro.
• Rendu : Il injecte le composant <Comments /> juste au-dessus des liens de navigation précédente/suivante (<Default />).
• Synchronisation Thème : Un Custom Element <giscus-comments> écoute :
  • Les changements de mutations sur document.documentElement (data-theme).
  • L’événement Starlight astro:after-swap.
  • Le stockage localStorage.getItem('starlight-theme').
  • Il envoie un message postMessage à l’iframe Giscus pour basculer instantanément entre thème clair et thème sombre sans rechargement.
• Activation conditionnelle par page : Le composant vérifie entry.data.giscus ?? true. Si une page a giscus: false dans son frontmatter, aucun widget Giscus n’est rendu.
• Dépendances : 0 dépendance runtime externe (utilise le script distant officiel https://giscus.app/client.js).

1.2 Paramètres requis

Quatre champs obligatoires sont vérifiés par validateAndNormalizeConfig :

1. repo (ex: 'audyssee/PP')
2. repoId (identifiant GraphQL du repo sur GitHub, ex: 'R_...')
3. category (nom de la catégorie de discussion GitHub, ex: 'General' ou 'Q&A')
4. categoryId (identifiant GraphQL de la catégorie, ex: 'DIC_...')

1.3 Prérequis GitHub & Giscus

Pour que les discussions s’affichent réellement :

1. Les GitHub Discussions doivent être activées sur le dépôt GitHub cible.
2. L’application GitHub Giscus doit être autorisée sur le dépôt.
3. Le configurateur https://giscus.app permet de récupérer repoId et categoryId.

---

2. Cycle DOC → SPEC → CODE → TEST → INTÉG

Phase 1 : DOC (Documentation préliminaire)

• Vérifier la compatibilité des schémas de contenu Astro v5 / Starlight 0.42.
• Valider la gestion des variables d’environnement (.env et .env.example) pour ne pas hardcoder les identifiants GitHub.

Phase 2 : SPEC (Spécification de l’intégration)

• Ordre des plugins dans apps/web/astro.config.mjs :
  1. starlightViewModes(...)
  2. starlightSidebarTopics(...)
  3. starlightGiscus(...)
  4. starlightPageActions(...)
  5. starlightDocSearch(...)
• Schéma de collection dans apps/web/src/content.config.ts :
  • Ajouter giscus: z.boolean().optional().default(true) dans l’extension du schéma docs.
• Variables d’environnement :
  • PUBLIC_GISCUS_REPO
  • PUBLIC_GISCUS_REPO_ID
  • PUBLIC_GISCUS_CATEGORY
  • PUBLIC_GISCUS_CATEGORY_ID
  • Valeurs par défaut fallback propres si variables absentes pour ne pas bloquer le build local.

Phase 3 : CODE (Implémentation)

1. Installation du paquet :

   pnpm --filter amn-astro add starlight-giscus@1.2.0

2. Mise à jour du schéma de contenu :
   • Fichier : apps/web/src/content.config.ts
   • Déclaration du champ optionnel giscus avec default(true).
3. Mise à jour de la configuration Starlight :
   • Fichier : apps/web/astro.config.mjs
   • Importation de starlightGiscus from 'starlight-giscus'.
   • Ajout dans plugins avec mapping pathname, chargement différé lazy: true, et support thème dynamique.
4. Mise à jour des variables d’environnement d’exemple :
   • Fichier : .env.example

Phase 4 : TEST (Validation locale)

1. Validation statique et typage :

   pnpm --filter amn-astro run typecheck # (astro check)

2. Build de production :

   pnpm --filter amn-astro run build

3. Test fonctionnel dans le navigateur :
   • Accéder à une page de documentation publique (ex: http://localhost:8787/gettingstarted/01-setup-local/).
   • Vérifier la présence de la section Giscus en bas de page (au-dessus de la pagination).
   • Basculer le mode sombre / clair et vérifier la mise à jour dynamique du thème du widget.
   • Tester l’exclusion sur une page avec giscus: false dans le frontmatter.

Phase 5 : INTÉG (Capitalisation & Documentation)

• Rédiger la documentation d’intégration dédiée :
  docs/L2_Presentation/astro/starlight/Starlight-Plugin-Giscus.md
• Mettre à jour test-docs/starlight-site-update.md (marquer le point 3 comme complété).

---

3. Matrice de Risques & Atténuations

Risque	Impact	Solution / Atténuation
Erreur au build si repoId ou categoryId est absent	Échec du démarrage Astro	Fournir des fallbacks dans astro.config.mjs ou configurer des variables par défaut.
Dépôt GitHub privé ou Discussions désactivées	Message d’avertissement dans l’iframe Giscus	L’iframe gère nativement l’erreur sans casser l’affichage de la page de documentation.
Conflit de composant Pagination	Écrasement mutuel	Aucun autre plugin n’override Pagination (SidebarWithAuth override Sidebar, pas Pagination).
Pages internes (ADR, SOP, GettingStarted) commentables	Commentaires involontaires sur docs privées	Possibilité de désactiver via giscus: false par page ou par catégorie.

---

4. Prochaine étape

Attendre la validation du plan avant de passer à l’installation du paquet (pnpm add starlight-giscus) et à l’exécution de la phase CODE.