Adding a comment system to a jekyll blog sounds easy — until it isn’t.

I wanted something minimal, privacy-respecting, and built right into github. Disqus was bloat. Utterances was limited. Giscus? Perfect.

But the road to setting it up was chaos. Here’s what I hit, how I fixed it, and a clean tutorial to help you avoid the same mess.

❌ Real Errors I Hit (And How I Fixed Each One)### 1. Wrong Repo FormatAt first, I tried setting up Giscus with this:

1
2
arenredd/arenredd/comment-engine

🧱 Wrong. That’s not how github repo paths work.

✅ Fix: Changed it to the correct format:

1
2
arenredd/comment-engine

2. Giscus Not Installed on RepoGiscus gave me this lovely error:

“Cannot use giscus on this repository.”

✅ Fix: Went to https://github.com/apps/giscus, clicked Configure, and installed it on the comment-engine repo only.

3. No Discussion CategoryEven after installation, Giscus didn’t detect any category.

✅ Fix: Opened the repo → Discussions → Created a new category called:

1
2
Blog Comments

Set it to Announcements type (so only maintainers can start threads).

4. Couldn’t Find the category_idgithub hides this deep. Inspecting HTML didn’t help.

✅ Fix: Used github’s GraphQL Explorer and ran this:

1
2
3
4
5
6
7
8
9
10
11
12
{
  repository(owner: "ArenRedd", name: "comment-engine") {
    discussionCategories(first: 10) {
      nodes {
        id
        name
      }
    }
  }
}


Grabbed the id for “Blog Comments” → pasted into _config.yml.

5. Didn’t Know the repo_id✅ Fix: Ran this in the browser console:

1
2
3
4
fetch("https://api.github.com/repos/ArenRedd/comment-engine")
  .then(res => res.json())
  .then(data => console.log("repo_id:", data.node_id));

Copied the repo_id result and dropped it in.

🛠️ The Final Working _config.yml Giscus Block```yaml

comments:
active: giscus
giscus:
repo: ArenRedd/comment-engine
repo_id: R_kgDOOwlWwQ
category: Blog Comments
category_id: DIC_kwDOOwlWwc4Cql_Y
mapping: pathname
input_position: bottom
lang: en

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

No more errors. No more guessing.



## 🚀 Clean Giscus Setup Tutorial (If You’re Starting Fresh)Here’s the process boiled down to a checklist:


### ✅ Step-by-Step:
- **Create a new public repo** just for comments:


 ```bash
arenredd/comment-engine

  • Enable Discussions in repo settings.

  • Create a Discussion Category called Blog Comments (type: Announcements).

  • Install Giscus github App

→ https://github.com/apps/giscus

  • Get your repo ID

Open console and run:

1
2
3
4
fetch("https://api.github.com/repos/YOUR_USERNAME/comment-engine")
  .then(res => res.json())
  .then(data => console.log(data.node_id));

  • Get your category ID

Use github’s GraphQL Explorer:

1
2
3
4
5
6
7
8
9
10
11
{
  repository(owner: "YOUR_USERNAME", name: "comment-engine") {
    discussionCategories(first: 10) {
      nodes {
        id
        name
      }
    }
  }
}

  • Update your _config.yml

Add the full Giscus block like above under comments:.

  • Commit and push your changes
1
2
3
4
git add .
git commit -m "Enable Giscus comments"
git push

🧠 Final ThoughtsNow my jekyll blog has github-native comments with zero bloat. No cookies. No trackers. Just clean Markdown and community interaction.

And yeah — I broke everything along the way, but I built it back up better.

If you’re setting up Giscus and hit roadblocks, just come back to this post. I’ve walked the fire path for you 🔥

🗨️ Got Questions?Scroll down to the bottom of this post — the Giscus comment box is waiting.

(Yes, it’s meta. You’re commenting on the post about comments. Welcome to the loop.)