How to Set Up Giscus Comments for Your Website - Complete Technical Guide

How to Set Up Giscus Comments - Complete Technical Guide

If you want to add a clean, GitHub-powered comment system to your website, Giscus is one of the best options. It stores comments as GitHub Discussions, requires no backend, and has zero infrastructure costs.

This guide walks you through everything required to get Giscus comments working on your website.

What is Giscus?

Giscus is a comments system powered by GitHub Discussions. Instead of maintaining a separate database:

Comments are stored as GitHub Discussions

Users authenticate with their GitHub account

Everything is public, transparent, and version-controlled

No ads, no tracking, no data selling

Perfect for developer-focused audiences and open-source projects.

Prerequisites

Before you start, you'll need:

A GitHub account

A repository where you want to store comments (public or private)

A personal access token (PAT) with public_repo scope (for GraphQL queries)

Step 1: Create a Repository for Comments

First, create a dedicated GitHub repository to store all comments:

Q-Z-L-Corp/giscus-comments

This repository will contain all the GitHub Discussions that become your website comments. Keep it public so comments are visible to everyone.

Why a separate repo?

Keeps your main repository clean

Makes it easy to manage discussion settings separately

Allows you to archive or reset comments independently

Step 2: Enable GitHub Discussions

Go to your comments repository settings:

Path: Settings → General → Features

Check the Discussions checkbox:

☑ Discussions

Without Discussions enabled, Giscus cannot store or retrieve comments.

Create Discussion Categories

After enabling Discussions, go to the Discussions tab and set up categories. By default, GitHub creates an "Announcements" category. Create a category for your use case:

Example: "Blog Comments"

Name: Blog Comments

Description: Comments on blog posts from qz-l.com

Emoji: 💬

You'll need the Category ID later (more on that in Step 5).

Step 3: Install the Giscus GitHub App

Giscus needs a GitHub App to read and write discussions on your behalf.

Install here: https://github.com/apps/giscus

During installation:

Select your GitHub account or organization

Select "Only select repositories"

Choose your comments repository (e.g., Q-Z-L-Corp/giscus-comments)

Click "Install"

The app will request permissions for:

Discussions (read/write comments)

Contents (optional, for metadata)

Metadata (optional, for repo info)

Once installed, Giscus is authorized to create and manage discussions in your repo.

Step 4: Get Your Repository ID (repoId)

Giscus requires the GraphQL repository ID, not the repository name. To get it, you'll query GitHub's GraphQL API.

Create a GitHub Personal Access Token

Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)

Click "Generate new token (classic)"

Name it: Giscus Setup

Select scopes: public_repo (for public repos)

Click "Generate token"

Copy the token (you'll use it in the next step)

Query the Repository ID

Use the GitHub GraphQL Explorer or your terminal:

GraphQL Query:

query {
repository(owner: "Q-Z-L-Corp", name: "giscus-comments") {
id
name
}
}

Using cURL:

curl -X POST https://api.github.com/graphql \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "query { repository(owner: \"Q-Z-L-Corp\", name: \"giscus-comments\") { id name } }"
}'

Response:

{
"data": {
"repository": {
"id": "R_kgDOQX9xSQ",
"name": "giscus-comments"
}
}
}

Your repoId is: R_kgDOQX9xSQ

Save this value—you'll need it in the Giscus component.

Step 5: Get Your Discussion Category ID (categoryId)

Now query for your discussion categories to get the categoryId:

GraphQL Query:

query {
repository(owner: "Q-Z-L-Corp", name: "giscus-comments") {
discussionCategories(first: 20) {
nodes {
id
name
slug
description
}
}
}
}

Using cURL:

curl -X POST https://api.github.com/graphql \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "query { repository(owner: \"Q-Z-L-Corp\", name: \"giscus-comments\") { discussionCategories(first: 20) { nodes { id name slug description } } } }"
}'

Response:

{
"data": {
"repository": {
"discussionCategories": {
"nodes": [
{
"id": "DIC_kwDOQX9xSc4Cx7Fn",
"name": "Blog Comments",
"slug": "blog-comments",
"description": "Comments on blog posts from qz-l.com"
}
]
}
}
}
}

Your categoryId is: DIC_kwDOQX9xSc4Cx7Fn

Step 6: Install Giscus in Your Project

Install the NPM Package

npm install @giscus/react

Or with yarn:

yarn add @giscus/react

Create a Giscus Component

Create a new file components/GiscusComments.tsx:

"use client";

import { useEffect } from "react";
import Giscus from "@giscus/react";

export default function GiscusComments() {
useEffect(() => {
console.log("Giscus component mounted");
}, []);

return (

Comments
<Giscus
id="comments"
repo="Q-Z-L-Corp/giscus-comments"
repoId="R_kgDOQX9xSQ"
category="Blog Comments"
categoryId="DIC_kwDOQX9xSc4Cx7Fn"
mapping="pathname"
strict="0"
reactionsEnabled="1"
emitMetadata="0"
inputPosition="top"
theme="light"
lang="en"
loading="lazy"
/>

);
}

Key props explained:

repo: Your repository in owner/name format

repoId: From your GraphQL query (Step 4)

categoryId: From your GraphQL query (Step 5)

mapping: How to match page → discussion

pathname: Use the current URL path

url: Use the full URL

title: Use the page title

specific: Use a custom term

reactionsEnabled: Allow emoji reactions

inputPosition: Where the comment form appears (top or bottom)

theme: light, dark, or preferred_color_scheme

loading: lazy for lazy loading (recommended)

Use the Component

In your page component (e.g., Next.js blog post page):

import GiscusComments from "@/app/components/Giscus";
import { Suspense } from "react";

export default function BlogPostPage() {
return (

{/* Your blog post content */}
Post content here...

{/* Comments section */}
<Suspense fallback={ }>
<GiscusComments />
</Suspense>

);
}

That's it! Since GiscusComments is marked with "use client", it automatically renders on the client side even though it's imported in a Server Component.

The Suspense boundary shows a loading placeholder while the Giscus iframe loads.

Step 7: Verify Everything Works

Load your page in the browser

Scroll to the comments section

Sign in with GitHub (if not already logged in)

Write a test comment

Check your discussions repo to see the comment as a GitHub Discussion

Advanced Configuration

Using a Custom Mapping Strategy

If you want all comments in a single discussion:

<Giscus
mapping="specific"
term="Blog Comments"
// ... other props
/>

Dark Mode Support

const theme = isDarkMode ? "dark" : "light";

<Giscus
theme={theme}
// ... other props
/>

Handling Lazy Loading

Giscus iframe content loads asynchronously. For better UX, add a loading skeleton:

const [isLoading, setIsLoading] = useState(true);

<Suspense fallback={

}>
<GiscusComments onLoad={() => setIsLoading(false)} />
</Suspense>

Troubleshooting

"404 Not Found" Error

Cause: Wrong repoId or categoryId, or Giscus app not installed.

Fix:

Double-check repoId and categoryId from GraphQL queries

Verify Giscus app is installed on the repo

Verify Discussions are enabled

Comments Not Showing

Cause: SSR (server-side rendering) issue, or Giscus script not loading.

Fix:

Use dynamic() with ssr: false (as shown in Step 6)

Check browser DevTools Console for errors

Verify Giscus script loads from https://giscus.app

"Not Authorized" When Trying to Comment

Cause: User not logged in to GitHub, or Giscus app permissions missing.

Fix:

User must sign in with GitHub

Reinstall Giscus app with required permissions

Why We Chose Giscus

After evaluating many comment systems, we chose Giscus for qz-l because:

✅ GitHub-native – Comments are part of your repo
✅ Zero backend – No database to manage
✅ Free forever – GitHub Discussions are free
✅ Privacy-first – No tracking, no ads
✅ Transparent – All discussions are public
✅ Developer-friendly – Perfect for technical audiences

Next Steps

Now that you have Giscus set up:

Monitor discussions – Check your repo's Discussions tab regularly

Respond to comments – Engage with your audience

Archive old discussions – Keep the repo organized

Customize styling – Adjust theme and component styling as needed

Have questions about setting up Giscus? Drop a comment below! This post has comments enabled—try it out. 👇

Found a mistake or have suggestions? Your feedback helps us improve this guide for other developers.

This guide was based on our experience setting up Giscus for the qz-l blog. Check out the live implementation at qz-l.com/blog.