Guide d'implémentation de Giscus

Introduction

Giscus est un système de commentaires gratuit, open-source et sans publicité, basé sur les Discussions GitHub. Il permet à vos visiteurs de laisser des commentaires sur vos pages MD, tout en vous garantissant une totale propriété de vos données.

Prérequis

Étape 1 : Préparer le dépôt GitHub

1.1 Vérifier ou créer un dépôt public

1.2 Activer les Discussions

  1. Allez dans l'onglet Settings de votre dépôt.
  2. Dans la section General, trouvez l'option Features.
  3. Cochez la case Discussions.
  4. Cliquez sur Set up discussions si nécessaire.

1.3 Installer l'application Giscus

  1. Rendez-vous sur la page de l'application : giscus app.
  2. Cliquez sur Install.
  3. Choisissez Only select repositories.
  4. Sélectionnez votre dépôt public.
  5. Confirmez l'installation.

Étape 2 : Générer le script d'intégration

2.1 Accéder au générateur

Rendez-vous sur giscus.app (pensez à passer en français en bas de page).

2.2 Remplir les paramètres

Champ Valeur recommandée
Repository votre-identifiant/votre-depot (ex: john/commentaires)
Page ↔️ Discussion Mapping Discussion title contains page pathname
Discussion Category General ou Announcements
Features Activer les réactions (emoji)
Theme preferred_color_scheme (adaptatif)
Language Français

2.3 Copier le script

En bas de page, copiez le script <script> généré. Il contient des identifiants uniques comme data-repo-id et data-category-id qu'il ne faut jamais modifier.

Étape 3 : Intégration dans votre site

3.1 Structure du fichier de configuration (config.ini)

[comments] enabled = true # ou false pour désactiver globalement

{% if config.comments.enabled %}
  <div class="giscus-comments" style="margin-top: 3rem; border-top: 1px solid #e5e7eb; padding-top: 2rem;">
    <h3 style="font-size: 1.25rem; font-weight: 600; margin-bottom: 1.5rem;">💬 Commentaires</h3>

    <script src="https://giscus.app/client.js"
            data-repo="[TON-REPO]"
            data-repo-id="[TON-REPO-ID]"
            data-category="[TA-CATEGORIE]"
            data-category-id="[TON-CATEGORY-ID]"
            data-mapping="pathname"
            data-strict="0"
            data-reactions-enabled="1"
            data-emit-metadata="0"
            data-input-position="bottom"
            data-theme="preferred_color_scheme"
            data-lang="fr"
            data-loading="lazy"
            crossorigin="anonymous"
            async>
    </script>
  </div>
{% endif %}

Sites utilisant Giscus comme système de commentaires

Voici une sélection de sites et projets qui utilisent Giscus, classés par catégorie.

Sites à fort trafic et documentations techniques

Blogs et sites personnels

Intégrations avec des générateurs de sites

Autres usages notables

Pourquoi ces sites ont choisi Giscus

"Une solution open-source qui utilise les Discussions GitHub, permettant de partager facilement des réflexions et d'interagir avec le contenu en utilisant votre compte GitHub."

Où observer le rendu en direct

Si tu veux voir le rendu exact, je te recommande de visiter :

Sites utilisant Giscus comme système de commentaires

Voici une sélection de sites et projets qui utilisent Giscus, classés par catégorie.

Sites à fort trafic et documentations techniques

Blogs et sites personnels

Intégrations avec des générateurs de sites

Autres usages notables

Pourquoi ces sites ont choisi Giscus

"Une solution open-source qui utilise les Discussions GitHub, permettant de partager facilement des réflexions et d'interagir avec le contenu en utilisant votre compte GitHub."

Où observer le rendu en direct

Je recommande de visiter :

Où tester Giscus en vrai ?

Pour voir le système en action et même laisser un commentaire test, voici une sélection de sites qui utilisent Giscus.

Sites avec commentaires actifs

Voici quelques sites où tu peux voir Giscus en fonctionnement :

Comment tester ?

  1. Ouvre l'un de ces sites dans ton navigateur.
  2. Scrolle jusqu'en bas d'un article de blog.
  3. Connecte-toi avec ton compte GitHub (le bouton apparaît automatiquement).
  4. Laisse un commentaire test pour voir le rendu en direct.

Exemples d'intégration par framework

Si tu veux voir comment Giscus s'intègre techniquement :

Ce que tu verras

Une fois connecté, tu pourras :

Les commentaires que tu laisses apparaîtront dans les Discussions GitHub du site [citation:9].

Où tester Giscus en vrai ?

Voici des sites où tu peux voir Giscus en fonctionnement et laisser un commentaire test.

Sites avec Giscus actif

Comment tester ?

  1. Ouvre l'un de ces sites.
  2. Scrolle en bas d'un article.
  3. Clique sur "Sign in with GitHub".
  4. Laisse un commentaire test.

Exemples par framework

Ce que tu verras

Sites avec Giscus actif (liens vérifiés)

Voici des sites où tu peux voir Giscus en fonctionnement et tester les commentaires.

Sites confirmés avec Giscus

Sites avec démonstration technique

Comment tester

  1. Ouvre l'un de ces sites.
  2. Scrolle en bas d'un article.
  3. Connecte-toi avec ton compte GitHub.
  4. Laisse un commentaire test.

Pages de démonstration officielles

Ce que tu verras

Comment concilier pages en cache et commentaires Giscus

Le cache n'est pas un problème

Le cache (navigateur ou générateur statique) n'affecte pas Giscus car le système s'exécute côté client, dans le navigateur de l'utilisateur.

Giscus va chercher les commentaires en direct au chargement de la page.

Le vrai sujet : l'identification des pages

Giscus doit associer chaque page de ton site à une Discussion GitHub unique.

Pour cela, il utilise un "mappage" (mapping) basé sur un identifiant.

Solution 1 : Mapper par chemin (recommandé)

Giscus utilise le chemin de la page comme identifiant.

Exemple :

Code à insérer dans le template :


<script src="https://giscus.app/client.js"
        data-repo="[TON-REPO]"
        data-repo-id="[TON-REPO-ID]"
        data-category="[TA-CATEGORIE]"
        data-category-id="[TON-CATEGORY-ID]"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="fr"
        data-loading="lazy"
        crossorigin="anonymous"
        async>
</script>

---