Starlight Giscus

Version : starlight-giscus@1.2.0
Starlight : @astrojs/starlight@0.42.4
Intégré le : 2026-10-13
Doc officielle : https://dragomano.github.io/starlight-giscus/
Repo cloné : ~/astro/starlight-giscus

---

1. Objectif

Permettre aux lecteurs de laisser leurs impressions, questions et remarques, et aux contributeurs de collaborer directement sur la documentation sans quitter le site, via les GitHub Discussions.

Les commentaires sont persistés directement sous forme de discussions sur le dépôt GitHub public désigné (audyssee/giscus).

---

2. Installation

Dans le workspace de l’application Astro (apps/web) :

pnpm add starlight-giscus

---

3. Variables d’environnement

Les identifiants Giscus sont injectés via le fichier /.env et documentés dans /.env.example :

# Giscus Comments Configuration
PUBLIC_GISCUS_REPO="audyssee/giscus"
PUBLIC_GISCUS_REPO_ID="R_kgDOVH5Mug"
PUBLIC_GISCUS_CATEGORY="General"
PUBLIC_GISCUS_CATEGORY_ID="DIC_kwDOVH5Mus4DIVel"

Note : Ces identifiants sont générés automatiquement depuis l’interface https://giscus.app après avoir activé les Discussions et installé l’app GitHub Giscus sur le dépôt cible.

---

4. Extension du Schéma de Contenu

Pour autoriser et typer la désactivation du widget page par page, le schéma de la collection docs dans apps/web/src/content.config.ts est étendu avec le champ giscus :

apps/web/src/content.config.ts

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';
import { z } from 'astro/zod';

const docs = defineCollection({
  loader: docsLoader(),
  schema: docsSchema({
    extend: z.object({
      // Champ de visibilité : public ou private (par défaut)
      visibility: z.enum(['public', 'private']).default('private'),
      // Champ Giscus : autoriser ou désactiver les commentaires par page
      giscus: z.boolean().optional().default(true),
    }),
  }),
});

---

5. Configuration dans astro.config.mjs

Le plugin est importé et déclaré dans le tableau plugins de Starlight :

apps/web/astro.config.mjs

import starlightGiscus from 'starlight-giscus';

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightViewModes({...}),
        starlightSidebarTopics([...], {...}),
        starlightGiscus({
          repo: process.env.PUBLIC_GISCUS_REPO || 'audyssee/giscus',
          repoId: process.env.PUBLIC_GISCUS_REPO_ID || 'R_kgDOVH5Mug',
          category: process.env.PUBLIC_GISCUS_CATEGORY || 'General',
          categoryId: process.env.PUBLIC_GISCUS_CATEGORY_ID || 'DIC_kwDOVH5Mus4DIVel',
          mapping: 'pathname',
          reactions: true,
          inputPosition: 'bottom',
          lazy: true,
        }),
        starlightPageActions(),
        starlightDocSearch({...}),
      ],
    }),
  ],
});

Options de configuration retenues

Option	Valeur	Description
repo	audyssee/giscus	Dépôt GitHub public hébergeant les discussions
repoId	R_kgDOVH5Mug	ID GraphQL du dépôt cible
category	General	Catégorie de discussion GitHub ciblée
categoryId	DIC_kwDOVH5Mus4DIVel	ID GraphQL de la catégorie
mapping	'pathname'	Associe la discussion au chemin URL de la page de doc
reactions	true	Active la barre d’émoticônes / réactions
inputPosition	'bottom'	Formulaire de réponse situé en dessous des messages
lazy	true	Chargement différé de l’iframe lorsque le lecteur défile

---

6. Architecture & Mécanisme d’Injection

6.1 Surcharge du composant Pagination

starlight-giscus injecte automatiquement le composant <Comments /> en surchargeant components.Pagination de Starlight :

starlight-giscus/overrides/Pagination.astro

---
import Default from '@astrojs/starlight/components/Pagination.astro';
import Comments from '../components/Comments.astro';
---

<Comments />
<Default />

Les commentaires s’affichent ainsi harmonieusement juste au-dessus des boutons de navigation « Page précédente » et « Page suivante ».

6.2 Synchronisation automatique des Thèmes (Dark / Light)

Le composant <giscus-comments> injecte un script en ligne et un Custom Element qui :

• Détecte le thème initial depuis localStorage.getItem('starlight-theme') et window.matchMedia('(prefers-color-scheme: dark)').
• Observe les mutations de l’attribut data-theme sur document.documentElement.
• Écoute l’événement de navigation Starlight astro:after-swap.
• Envoie automatiquement un postMessage à l’iframe Giscus (https://giscus.app) avec { giscus: { setConfig: { theme } } } sans rechargement de page.

6.3 Désactivation conditionnelle par page

Pour masquer la section des commentaires sur une page spécifique (ex: documents confidentiels internes, pages d’index ou synthèses) :

---
title: "Document interne"
giscus: false
---

Le composant vérifie entry.data.giscus ?? true et omet le rendu du widget si giscus === false.

---

7. Tests de Validation

• Compilation TypeScript (pnpm run typecheck / astro check) : 0 erreurs, 0 warnings
• Build de production Cloudflare (pnpm run build) : Succès (code 0)
• Dans le navigateur (http://localhost:8787/gettingstarted/01-setup-local/) :
  • Section de commentaires présente avant la pagination.
  • Bascule du thème Clair/Sombre répercutée dans l’iframe Giscus.
  • Connexion GitHub fonctionnelle pour réagir ou commenter.