Skip to content
AMN Docs

Starlight Giscus

Starlight Giscus

Intégration du plugin starlight-giscus pour les commentaires et retours de lecture

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) :

Terminal window
pnpm add starlight-giscus

3. Variables d’environnement1/2

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"

3. Variables d’environnement2/2

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 Contenu1/2

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 :

4. Extension du Schéma de Contenu2/2

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 retenues1/2

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

Options de configuration retenues2/2

Option Valeur Description
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.
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare