Adding Giscus Comments to Your Academic Pages Website

3 minute read

Published:

If you’ve forked the Academic Pages template for your GitHub Pages website and want to add a commenting system, Giscus is an excellent choice. This guide will walk you through setting up Giscus comments on your Academic Pages website.

What is Giscus?

Giscus is a comments system that uses GitHub Discussions to store comments. When someone comments on your blog post, it actually creates a discussion in your GitHub repository. The main advantages are:

  • Free and open source
  • No ads
  • No external database needed
  • Spam protection (since commenters need GitHub accounts)
  • Comments are stored in your repository

Prerequisites

  1. Your repository must be public
  2. GitHub Discussions must be enabled in your repository
  3. You have forked the Academic Pages template and have it running

Step-by-Step Setup Guide

1. Enable GitHub Discussions

First, enable GitHub Discussions in your repository:

  1. Go to your repository settings
  2. Scroll down to the “Features” section
  3. Check the box next to “Discussions”

2. Install Giscus GitHub App

  1. Go to https://github.com/apps/giscus
  2. Click “Install”
  3. Select your repository and complete the installation

3. Configure Giscus

  1. Visit https://giscus.app
  2. In the configuration section:
    • Enter your repository name (e.g., username/username.github.io)
    • Choose “pathname” for Page ↔️ Discussions Mapping
    • Enable “Use strict title matching”
    • Choose “Announcements” as the Discussion Category
    • Select your preferred theme (e.g., “light”)
    • Select other options as desired (reactions, lazy loading, etc.)

Make note of the following values from the generated script:

  • data-repo
  • data-repo-id
  • data-category
  • data-category-id

4. Update _config.yml

Modify your _config.yml file to use Giscus. Find the comments section and update it:

comments:
  provider: "custom"
  giscus:
    repo: "username/username.github.io"  # Your repository name
    repo_id: "R_xxx"                     # Your repository ID
    category: "Announcements"            # The discussion category
    category_id: "DIC_xxx"              # The category ID
    mapping: "pathname"
    strict: true
    reactions_enabled: '1'
    theme: "light"
    language: "en"
    loading: "lazy"

5. Add Giscus Script

Locate the file _includes/comments-providers/custom.html and replace its contents with:

<!-- start custom comments snippet -->

  <div id="giscus-comments">
    <script src="https://giscus.app/client.js"
        data-repo="divyaprakash-iitd/divyaprakash-iitd.github.io"
        data-repo-id="R_kgDONHJ7lA"
        data-category="Announcements"
        data-category-id="DIC_kwDONHJ7lM4Ckx2q"
        data-mapping="pathname"
        data-strict="1"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="light"
        data-lang="en"
        data-loading="lazy"
        crossorigin="anonymous"
        async>
    </script>
    <div class="giscus"></div>
  </div>

<!-- end custom comments snippet -->

6. Enable Comments on Posts

To enable comments on a specific blog post, add comments: true to the front matter of your post:

---
title: 'Your Blog Post Title'
date: 2024-01-01
permalink: /posts/2024/1/blog-post-1/
comments: true
tags:
  - tag1
  - tag2
---

Note: By default, the Academic Pages template enables comments for all posts in _config.yml under the defaults section:

defaults:
  # _posts
  - scope:
      path: ""
      type: posts
    values:
      layout: single
      author_profile: true
      read_time: true
      comments: true  # This line enables comments for all posts
      share: true
      related: true

If you want to disable comments for a specific post, you’ll need to explicitly set comments: false in that post’s front matter.

Troubleshooting

  1. Comments not appearing?
    • Check if GitHub Discussions is enabled
    • Verify your repository name and IDs in _config.yml
    • Make sure the post has comments: true (or is not explicitly set to false)
  2. Error in loading comments?
    • Check browser console for errors
    • Verify the Giscus app is installed on your repository
    • Make sure your repository is public
  3. Comments appearing on unwanted pages?
    • Check your _config.yml defaults section
    • Add comments: false to specific posts or pages where you don’t want comments

Additional Notes

  • Comments are stored as GitHub Discussions in your repository
  • Users need a GitHub account to comment
  • You can moderate comments through GitHub’s interface
  • The theme will automatically match your website’s theme
  • Comments are loaded lazily to improve page performance

Leave a Comment