Enable giscus in Distill

How to use the giscus commenting system on a Distill blog

Note: This post was originally written by Joel Nitta and copied here on November 29, 2021 - see the original post here for a potentially updated version.

TL;DR

• giscus is a free, open-source commenting system for blogs that uses the GitHub API
• giscus uses GitHub Discussions (not Issues) to store data
• I show how to enable giscus on a Distill blog

Figure 1: Image by Adam Solomon on unsplash.

Like many R-bloggers these days, I have made some changes: I switched from blogdown to Distill

blogdown and Distill are R packages for making websites. In a nutshell, Distill is much simpler to use than blogdown, at the cost of some design flexibility. For more about making the switch, you can get caught up with posts from Thomas Mock, Frie Preu, Lisa Lendway, and Andreas Handel.

¹ , and from disqus to utterances

disqus and utterances are tools that let users comment on blog posts. Recently many R-bloggers have been moving away from disqus because it has a habit of tracking user’s data and causing page bloat. More recently, when I checked on my disqus account (in the process of migrating away!), it had a option to “opt-out” of data tracking, but that means data-tracking is on by default.

² . Several things about utterances appealed to me: free, open-source, no data tracking. But when I started using it, I immediately was turned off by the dual use of GitHub issues as a way to store comments. It just felt odd to have an issue that wasn’t an issue!

Fortunately, I’m not the only one to feel this way, and @laymonage actually did something about it: there is now a very similar app to utterances, called giscus. It offers almost the same functionality, but it uses GitHub Discussions as the place to store comments instead of Issues. This makes much more sense to me.

There are several blogposts

For example, Vebash Naidoo’s tutorial and Michael McCarthy’s post describing how to control the location of the comments section.

³ on how to enable utterances on Distill, but none that I’ve found so far on giscus. So, here goes!

1. Enable Discussions on your blog repo. Optionally, if you want to use a non-default Discussions category for storing giscus content, add a new category. I did this and called it “Comments”. As recommended by giscus, it’s a good idea to set the discussion format to “Announcement” so that non-authorized users can’t add content via the Discussions interface (only the giscus widget on your blog).

2. Install the giscus GitHub app and configure it to have access to your blog’s repo.

3. Go to the giscus app interface, scroll down to “configuration” and fill in the details for your blog. Once you’ve done so, further down you should see an HTML code block under “Enable giscus” populated with your information.

Figure 2: giscus configuration menu.

Figure 3: giscus HTML block. Once you fill in the fields in the configuration menu, the parts starting with [ENTER ...] will get automatically populated.

As described in Miles McBain’s blogpost, unfortunately in Distill, you can’t just paste the HTML directly into an Rmd file. It won’t show up. But the same work-around that he describes for utterances also happily works for giscus! Read on…

5. Add an .html file (I’ve called mine giscus.html) to the root of your blog repo that looks like this (and is based off of Miles’ HTML):

<script>
   document.addEventListener("DOMContentLoaded", function () {
     if (!/posts/.test(location.pathname)) {
       return;
     }

     var script = document.createElement("script");
     script.src = "https://giscus.app/client.js";
     script.setAttribute("data-repo", "[ENTER REPO HERE]");
     script.setAttribute("data-repo-id", "[ENTER REPO ID HERE]");
     script.setAttribute("data-category", "[ENTER CATEGORY NAME HERE]");
     script.setAttribute("data-category-id", "[ENTER CATEGORY ID HERE]");
     script.setAttribute("data-mapping", "pathname");
     script.setAttribute("data-reactions-enabled", "0");
     script.setAttribute("data-emit-metadata", "0");
     script.setAttribute("data-theme", "light");
     script.setAttribute("data-lang", "en");

     /* wait for article to load, append script to article element */
     var observer = new MutationObserver(function (mutations, observer) {
       var article = document.querySelector("d-article");
       if (article) {
         observer.disconnect();
         /* HACK: article scroll */
         article.setAttribute("style", "overflow-y: hidden");
         article.appendChild(script);
       }
     });

     observer.observe(document.body, { childList: true });
   });
 </script>

If you compare the above code with the HTML block in the giscus app (Fig. 3), you should be able to see how the script.setAttribute lines above map to the key-value pairs in the HTML block in the giscus app. All we have to do is copy the contents of the HTML block over to this giscus.html file. You can see what my giscus.html file looks like here.

6. Modify _site.yml so that the giscus.html file gets loaded on every Distill article page
   The _site.yml file is longer than this, but I’m just showing the relevant code to add. You can see my _site.yml file here.
   ⁴ :

output: 
  distill::distill_article:
    includes:
      in_header: giscus.html

That’s it! Or it should be anyways. I recommend trying a test comment to make sure everything is working (nobody will tell you otherwise…)