I just started using Jekyll and wanted to have comments. I’m using the al-folio theme, and a lot comes out of the box- including the usage of Giscus. Giscus seems pretty cool: The idea is that you can use a GitHub’s “Discussion” feature on a repo to store comments and make use of the GitHub OAuth as well.

Installation

Installation ought to have been easy, but I had never heard of Giscus and since I wasn’t using GitHub Pages (I host my Jekyll blog on its own server), I wasn’t sure how this would work.

The _config.yml file on my site has the following section:

# Giscus comments (RECOMMENDED)
# Follow instructions on https://giscus.app/ to setup for your repo to fill out
# the information below.
giscus:
  repo:                          # <your-github-user-name>/<your-github-repo-name>
  category: Comments             # name of the category under which discussions will be created
  mapping: title                 # identify discussions by post title
  strict: 1                      # use strict identification mode
  reactions_enabled: 1           # enable (1) or disable (0) emoji reactions
  input_position: bottom         # whether to display input form below (bottom) or above (top) the comments
  theme: preferred_color_scheme  # name of the color scheme (preferred works well with al-folio light/dark mode)
  emit_metadata: 0
  lang: en

The questions I had

  1. Did I need to set up a server or some sort of API to handle comments? If not, did I need to pay for it?
    • Answer: You can, but you don’t have to! You can use the giscus.app API for free!
  2. How are comments stored? Are they just saved in the repo as files?
    • They’re stored by using GitHub’s Discussion feature. There’s an API for it, and you can attach it to a repo.
    • They’re not saves as files in the repo.
  3. What does the repo need in order to work? Can anyone access the repo?
    • You’ll also need to set up to rights for read/write on Discussions and enable them.
    • Yes; you’ll need to make the repo public- but it doesn’t have to be the same repo as your blog if you don’t want it to be!
    • POTENTIAL TRAP: If you do this, and you happen to be using something like a GitHub action to deploy your blog- a GitHub action modeled after al-folio’s - watch out for a step to override the giscus.repo property on deploy. Took me a while to figure out why change the configuration wasn’t doing anything… :sweat_smile:
  4. I don’t really understand the main Giscus page- am I setting up something?
    • Not really, it’s just walking you through creating a valid configuration, and then rendering what the configuration should look like under the “Enable Giscus” section which generates the script with your configuration values.

Okay, so we’re good then?

Not quite- after creating a repo still didn’t work. Partly because I didn’t really understand #4; I figured my blog theme would handle it all. It almost did, but for some reason it didn’t include additional required properties such as the repo ID, and category ID. I discovered this when using Chrome tools- I could see the requests were failing.

Here’s what you need to do:

  1. What you probably already did: Use Giscus to make sure you get the repo configured right
    • Make the repo public if it’s not already OR (what I did) just create a new empty public repo.
    • Enable Discussions feature on the repo (I also actually clicked “Set up discussions”- but I don’t think this should be necessary)
    • Update permissions for read/write on the repo.
  2. Go back to your blog site. Make sure there is a script to use Giscus. You can either add it manually, or search if these already supports it. In my case, the al-folio theme has the script in _includes/Giscus.html.
  3. Make sure all the required configuration is set. In my case, the al-folio theme _config.yml file was missing the repo ID, and category ID. I added those. I got those from Giscus
  4. Make sure the category you’ve specified in your blog config matches a category on the discussion repo you’re using. In my case, I needed to add “Comments” category.

:tada:

Shout-out to da-in

When I was troubleshooting my blog’s usage of the Giscuss service, one of the problems I got after finally getting the right repo (“potential trap” I mentioned), I was still not able to make a comment because the category was misconfigured. However, I could see this error in Google Chrome’s dev tools: Unable to create discussion with request body.

I couldn’t find anything about it, until I saw this blog post: https://da-in.github.io/posts/Blog-Comments/ - it wasn’t an English but I was able to use Google Translate and the mention regarding categories was all I needed to know where to look. Thanks, da-in! :heart: It’s in these moments that the global community of the internet feels tangible.