Add A Comment Section to My Blog with Giscus

Several years ago, GitHub released the GitHub Discussion feature that provides smoother experiences of iteracting with the audience other than GitHub Issues. This motivates the giscus project, which takes advantage of the GitHub Discussion search API to find the Discussion associated with a page and display them in a comment section. Therefore, visitors can sign in with their GitHub account and leave comments in this section provided by giscus, which were actually posted as comments in GitHub Discussion.

To enable giscus comments on a website, we basically need to do several things.

1. Select a public GitHub repository which has enabled the GitHub Discussion feature to hold comments. We can use a new repository or a existing repository, as long as it is public.
2. Install giscus as a GitHub APP from this page and allow it to access and modify data in the repository.
3. Configure how giscus maches pages and comments by going through intructions on this page. After configuration, giscus will give a short script that can be embedded into our website's template, appearing as a comment section.
4. Paste or integrate the generated code into our website's template. This step depends on how we create the site. I will give a detailed example for my site later.
5. Configure giscus.json. To ensure that giscus works properly on our website, we may need to create a giscus.json file at the root of the repository. This file can specify the domains that can load giscus; refer to their documentation. I will also give an example later that I use on my site.

First, I choose the current blog repository to hold both posts and comments. Then, I install and configure giscus and obtain the snippet to be used, which is stored in ./static/giscus.html and looks like

<p>Enjoyed the read? Like and share your thoughts below. Your feedback matters!</p>

<script src="https://giscus.app/client.js"
        data-repo="Dou-Meishi/org-blog"
        data-repo-id="R_kgDOLJfSOw"
        data-category="Announcements"
        data-category-id="DIC_kwDOLJfSO84CkxDd"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="light"
        data-lang="en"
        crossorigin="anonymous"
        async>
</script>

The data-repo refers to the public repo that enables GitHub Discussion and is used to store comments. The data-mapping is set to pathname, which means giscus will match a page with the comments in GitHub Discussion by searching its pathname.

As I showed in the previous post, this site is generated by Org-Static-Blog, a static site generator using org-mode. To add a comment section at the end of each post, I simply set the variable org-static-blog-post-comments to the content of ./static/giscus.html, i.e.,

(setq org-static-blog-post-comments (with-temp-buffer
  (insert-file-contents (format "%sstatic/giscus.html" dms/org-static-blog-root-dir))
  (buffer-string)))

Finally, I create a giscus.json at the root of my blog repository to allow giscus operates on this site.

{
  "origins": [
      "https://dou-meishi.github.io/org-blog"
   ],
  "originsRegex": [
      "https://localhost:[0-9]+",
  ],
  "defaultCommentOrder": "newest"
}

That's it! Every post generated by org-static-blog will now display a comment section. Visitors can login with GitHub account and leave their comments.

• Giscus (2021). Giscus. GitHub. https://github.com/giscus/giscus
• Zhauniarovich Y. (2023). Giscus: The New Commenting Engine for My Website. https://zhauniarovich.com/post/2021/2021-06-giscus/