How to Add a Giscus Comment Section to Your Next.js Blog (Complete Guide)

Introduction

After experimenting with Hugo and Notion for blogging, I decided to build my own blog project from scratch.
Here’s the repo 👉 https://github.com/836108186/blog_zxyj

Once I got the basics running using Tailwind + Next.js Starter Blog, I quickly realized something:

A blog without comments just feels a bit lonely — there’s no real conversation happening.

So, I compared several comment systems (like Disqus, Utterances, and Gitalk) and finally settled on Giscus — a backend-free comment system powered by GitHub Discussions.
Here’s my full setup guide and some pitfalls I ran into.

1. Create a GitHub Repository with Discussions Enabled

Before using Giscus, make sure you have a GitHub repository ready.
If you’re using Next.js Starter Blog, simply click “Use this template” at the top right of the repo to create your own blog.
Otherwise, just create a new repo manually — it’s quick.

2. Install the Giscus App

To allow visitors to post comments, you must install the Giscus App on GitHub.

1. Visit https://github.com/apps/giscus
2. Click Install (or Configure if you already have it installed);
3. Select the repository you want to use for comments.

After installation, Giscus gains permission to create and manage discussion threads under your repo’s Discussions tab.

3. Generate the Giscus Script

Go to https://giscus.app, and you’ll see a configuration generator.
Here’s what you need to do:

• Select your repo (e.g., username/blog-repo);
• Choose “Discussions” as the category;
• Adjust your theme and language;
• Copy the generated <script> code.

You’ll later paste this snippet into your blog’s article template.

4. Add the Giscus Script to Your Next.js Blog

Open your blog project (e.g., based on Next.js Starter Blog) and locate the component that renders post content — typically components/Comments.tsx or the bottom of your post layout file.

Paste your <script> snippet there. Example:

  <script
    src="https://giscus.app/client.js"
    data-repo="yourname/yourrepo"
    data-repo-id="repo id"
    data-category="General"
    data-category-id="Category ID"
    data-mapping="pathname"
    data-reactions-enabled="1"
    data-emit-metadata="0"
    data-theme="preferred_color_scheme"
    crossorigin="anonymous"
    async
  ></script>

Once saved, deploy your site again. Now your blog posts should display a comment section that connects directly to GitHub Discussions.

5. Common Issues & Tips

❌ Giscus not showing up?

• Double-check that the repository and category IDs match.
• Ensure your blog domain is listed under “allowed origins” in the Giscus app settings.

🌓 Dark mode issues?

• Use data-theme="preferred_color_scheme" to automatically switch themes based on the user’s system preference.

🔐 Permissions error?

• Reinstall the Giscus App and make sure it has access to your comment repo.