Skip to content
AMN Docs

Plan d'intégration — Starlight Giscus

Plan d'intégration — Starlight Giscus

Plan détaillé pour l'intégration du plugin starlight-giscus pour les commentaires et retours de lecture

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 Plugin1/3

  • 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 />).

1.1 Architecture du Plugin2/3

  • 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.

1.1 Architecture du Plugin3/3

  • 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)1/3

  • Ordre des plugins dans apps/web/astro.config.mjs :
    1. starlightViewModes(...)
    2. starlightSidebarTopics(...)
    3. starlightGiscus(...)
    4. starlightPageActions(...)
    5. starlightDocSearch(...)

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

  • 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.

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

  • 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 :
    Terminal window
    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 :
    Terminal window
    pnpm --filter amn-astro run typecheck # (astro check)
  2. Build de production :
    Terminal window
    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.

Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare