Adding Giscus Comments to Your Academic Pages Website
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
- Your repository must be public
- GitHub Discussions must be enabled in your repository
- 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:
- Go to your repository settings
- Scroll down to the “Features” section
- Check the box next to “Discussions”
2. Install Giscus GitHub App
- Go to https://github.com/apps/giscus
- Click “Install”
- Select your repository and complete the installation
3. Configure Giscus
- Visit https://giscus.app
- 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.)
- Enter your repository name (e.g.,
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
- 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)
- Error in loading comments?
- Check browser console for errors
- Verify the Giscus app is installed on your repository
- Make sure your repository is public
- 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
- Check your
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