How to Add Giscus Comments to a GitHub Pages Blog

Static sites have a comments problem. You can't run server-side code, so you can't store comments in a database. The traditional solution Disqus works, but it's heavy, slow, and embeds third-party tracking into every page.

Giscus solves this elegantly for developer blogs: it stores comments in your GitHub repository's Discussions, renders them via the GitHub API, and authenticates readers through their existing GitHub accounts. No new service to sign up for. No data leaving your repository.

Prerequisites

A GitHub Pages blog in a public repository
GitHub Discussions enabled on the repository
The Giscus GitHub App installed on the repository

The Manual Route (for existing static HTML blogs)

1Enable Discussions on your repository

Go to your GitHub repo → Settings → General → scroll to "Features" → check "Discussions." Click Save. This activates the Discussions tab on your repo.

2Install the Giscus GitHub App

Go to github.com/apps/giscus and click "Install." Grant it access to the specific repository where your blog is hosted. This is required for Giscus to post comments to your Discussions.

3Generate your Giscus embed script

Go to giscus.app. Enter your repository, select a mapping option (recommended: "Discussion title contains page URL"), choose your category, and pick a theme. The page will generate a <script> tag.

4Paste the script into your blog pages

Add the generated <script> tag to the bottom of the <body> in each blog post HTML file where you want comments to appear. Save and push to GitHub. Giscus will render a comment section automatically.

The script looks like this:

<script src="https://giscus.app/client.js"
  data-repo="yourusername/your-repo"
  data-repo-id="YOUR_REPO_ID"
  data-category="Comments"
  data-category-id="YOUR_CATEGORY_ID"
  data-mapping="url"
  data-reactions-enabled="1"
  data-theme="light"
  crossorigin="anonymous"
  async>
</script>

The data-repo-id and data-category-id values are generated automatically by giscus.app you don't need to look them up manually.

Verify it's working

After pushing, open a blog post in a private/incognito window. You should see a Giscus comments widget at the bottom of the page. Sign in with GitHub to post a test comment. Check your repository's Discussions tab the comment should appear there.

Giscus is built into Thooval.

If you're setting up a new GitHub Pages blog, Thooval embeds Giscus with a single settings toggle. Try it free for 7 days, then pay $15 once.

Buy Lifetime License $15 Download 7-day Trial

macOS 12+ · $15 One-time · No subscriptions

Common Issues

Comments not showing up

The most common cause: Discussions aren't enabled on the repo, or the Giscus GitHub App wasn't granted access to the specific repository. Re-check both in your repository settings and at github.com/apps/giscus.

Wrong discussion category

Giscus requires a specific Discussions category to work. When setting up on giscus.app, make sure the category you select actually exists in your repository's Discussions → Categories list.

Comments appear on all posts the same

This happens when data-mapping is set to "pathname" but your pages all share the same pathname. Change the mapping to "url" or "title" in your Giscus script and update the embed code on your pages.

Why Giscus Over Disqus

Disqus works but it slows your pages down significantly (it loads a large JavaScript bundle) and embeds cross-site tracking across every page where it's installed. Giscus is lightweight, privacy-respecting, and keeps all comment data in your own GitHub repository. For a developer blog, it's the clear choice.