blog post image
Andrew Lock avatar

Andrew Lock

~4 min read

Replacing Disqus with GitHub discussions using giscus

In my previous post I mentioned that I was considering Disqus with a GitHub-based commenting system (for various reasons I discussed in that post, but primarily because Disqus insists on showing ads). Every comment on that post suggested that giscus was the way to go, and in a poll I pot on Twitter, exactly 0% of people suggested sticking with Disqus:

Several people described success stories converting to giscus and utterances, so I was so sold.

So in this post, I describe the (very simple) approach I took to initially replacing Disqus with giscus on my blog!

Setting up the repository

Setting up giscus was a simple case of following the instructions from the home page, but I go through all of the steps here for completeness.

The giscus home page

The first decision to make is which GitHub repository is going to host your discussions. If you have a public repository for your blob/website, then I think it makes most sense to include them there, but if not, then you can easily create a new repository dedicated to the comments.

It's important to note that the repository must be public. If it's private, the comments won't show up when giscus tries to display them.

I decided to create a completely new repository, on the basis that my current blog repository is not public (for Reasons™), and that I can always move the discussions between repos later if I wanted!

After creating the repository, install the giscus app by navigating to the app page and following the instructions—I only installed it on the single repo, but you can install it on multiple repositories if you like.

After installing the app, navigate to your repository and go to the settings page. Scroll down to the Features section and enable discussions:

Enabling discussions in GitHub

As I'm only using this repo for discussions, I chose to disable all the other features (issues, Wiki etc). Now the repository is all set-up, it's time to generate our giscus install script.

Configuring giscus

You can read about giscus configuration on the app's page. This provides a nifty interactive UI for configuring your giscus script:

Configuring giscus using the UI

The following is how I configured my script:

  • Enter the repository you configured earlier
  • Choose Discussion title contains page pathname. Using the Title would be nicer, but as it's not guaranteed to be unique pathname or URL seems like the safe option.
  • Check Use strict title matching. This uses a hash to avoid partial match issues related to how GitHub search works.
  • Set Discussion category to Announcements. So that only you or giscus can create the "comment" discussion posts
  • Check Only search for discussions in this category
  • Features I enabled:
    • Enable reactions for the main post
    • Place the comment box above the comments
    • Load the comments lazily
  • Theme: Preferred color scheme

Once you've entered all these details, you'll have a script you can copy and paste into your app:

<script src=""

Copy the generated script (similar to the one above), and paste it into your HTML in whatever fashion makes sense for your blog.

Restrict where giscus will load your comments

The final step I took was to restrict the origins that giscus will load the discussions from my repo (so that when people inevitably scrape my blog posts, they at least don't also get the comments!).

To configure this, add a JSON file called giscus.json to your "discussions" repository:

  "origins": [

You can also add extra configuration to this JSON file, such as the default comment order (default is oldest to newest), or to configure more complex origins. You can see the advanced configuration docs here.

Next steps

So is that it? Well, giscus is now up and running on my blog, but there's one step left - I'd like to migrate the existing Disqus comments on my blog to giscus, but I haven't done that part yet. I plan to tweak Jürgen's repo for migrating Disqus to GitHub issues to work with discussions instead. I'll work on that soon, and report back!

Andrew Lock | .Net Escapades
Want an email when
there's new posts?