There are a few reasons why I’ve avoided adding a comment section to my blog these past two decades. Firstly, it can promote inappropriate and low effort responses… especially if comments can be made anonymously. As a result, my home page encourages readers to email me directly. I’ve received well over a thousand emails from readers over the years, and I’ve enjoyed replying to each one. Secondly, introducing a comment section requires the execution of dynamic content that usually stores comments within a database. I instead prefer to use a simple, static website for my personal blog that can be easily hosted anywhere I choose. This also means I don’t have to configure and maintain databases.

Recently, however, I’ve been getting more and more emails from readers requesting I add a comment section to my blog. And when one of my blog posts goes viral on Hacker News I often get several dozen of these emails within a few days. So, I’ve decided it’s time to add that section, but in a way that requires users prove their identity to discourage inappropriate or irrelevant (e.g., spam) comments that I’d need to remove.

This website is entirely written in Markdown text format and composited to webpages using the Hugo static website generator. Moreover, it is hosted in two separate locations: in my GitHub account at jasoneckert.github.io using the GitHub Pages feature, and on the triosdevelopers.com web server for fault tolerance. Each time I modify my web content, it pushes the new content to both locations.

Unlike systems like WordPress that provide dynamic content stored in a database out of the box, Hugo requires that I add those things manually. The easiest way to add comments to a Hugo-generated website is to leverage the Disqus third-party service. But I’m not keen on the idea of comments being stored on servers owned by some other entity that can do anything with that data. Another option is to leverage my Mastodon account for comments. But this requires I manually share each blog I post on Mastodon and then re-edit that same blog to include the Mastodon toot (post) ID number so that the comments made on Mastodon are displayed at the bottom.

So I decided to leverage the giscus app in GitHub to provide comments for my blog. Since giscus uses the GitHub Discussions feature to store comments, a separate database is not required. It’s also well documented and relatively easy to set up if you have web development knowledge. Because readers must have a GitHub account to post comments, anonymous posts are not allowed.

It also makes sense to store the main copy of my website and associated comments in the same repository on GitHub. Moreover, this repository can also be used to store comments for the copy of my website on triosdevelopers.com. And because it is open source, should giscus no longer be actively maintained in the future, I can always maintain the code myself and self-host the giscus app in GitHub (but I doubt that’ll happen).

Configuring giscus

To configure giscus to add a comment section to your GitHub Pages website composited with Hugo, you can follow these steps:

1. In the repository for your website on GitHub, enable the GitHub Discussions feature by navigating to Settings and selecting Discussions under the Features section.

2. Install the giscuss app in your GitHub account by navigating to https://github.com/apps/giscus (allow access to the repository for your website).

3. Go to https://giscus.app/ and supply the following giscus configuration information to generate a <script> block that can be used in Hugo:

• The location of your repository on GitHub (e.g., jasoneckert/jasoneckert.github.io)
• The method used to identify comment threads in Discussions (I chose Discussion title contains page pathname to ensure that I see the website path for each blog post in GitHub Discussions)
• The GitHub Discussions category (I chose Announcements to ensure that only giscus and I can create new discussions)
• Any giscus features you wish to use (I de-selected the default Enable reactions for the main post feature so that readers must type a reply instead of simply adding an emoji reaction, because that encourages thumbs down emojis without explanation)
• The theme for the comment section (there are many to choose from)

4. Copy the <script> block generated in the previous step. For my choices, this block resembles the following:

       <script src="https://giscus.app/client.js"
          data-repo="jasoneckert/jasoneckert.github.io"
          data-repo-id="yourIDhere"
          data-category="Announcements"
          data-category-id="yourCategoryIDhere"
          data-mapping="pathname"
          data-strict="0"
          data-reactions-enabled="0"
          data-emit-metadata="0"
          data-input-position="bottom"
          data-theme="noborder_gray"
          data-lang="en"
          crossorigin="anonymous"
          async>
       </script>   

5. Create a layouts/partials/giscus.html file in your Hugo directory and paste in your <script> block (I added the if enclosure to ensure I can globally disable commenting later, if necessary):

     {{- if (eq (.Site.Params.disableComments | default false) false) -}}
      {{- if (eq (.Params.disableComments | default false) false) -}}
       <script src="https://giscus.app/client.js"
          data-repo="jasoneckert/jasoneckert.github.io"
          data-repo-id="yourIDhere"
          data-category="Announcements"
          data-category-id="yourCategoryIDhere"
          data-mapping="pathname"
          data-strict="0"
          data-reactions-enabled="0"
          data-emit-metadata="0"
          data-input-position="bottom"
          data-theme="noborder_gray"
          data-lang="en"
          crossorigin="anonymous"
          async>
        </script>   
       {{- end -}}
      {{- end -}}

6. Override the appropriate HTML component of your Hugo template to refer to giscus.html. This will vary based on your actual Hugo template. In my template, I have a themes/theme/layouts/partials/prevNext.html that draws the previous and next navigation buttons at the bottom of each blog post. And since I wanted the comment section to be shown directly below those navigation buttons, I copied that file to layouts/partials/prevNext.html (to override the original copy) and added the following line to the bottom:

      {{ partial "giscus" . }}

7. Optionally modify the config.toml file in the root of your Hugo directory to include the same parameters from the <script> block for posterity (I like to see my website configuration in one place):

      [params.giscus]
        repo = "jasoneckert/jasoneckert.github.io"
        repoId = "yourIDhere"
        category = "Announcements"
        categoryID = "yourCategoryIDhere"
        mapping = "pathname"
        reactions = false
        inputPosition = "bottom"
        theme = "noborder_gray"

That’s it! You can now composite your website again with Hugo and push it to GitHub Pages to add a comment section to each blog post.

If you host your website elsewhere, you can still create and use the GitHub Discussions feature to store comments via giscus as long as you create a repository for it. In my case, the copy of my GitHub Pages website hosted on triosdevelopers.com also stores comments in the discussions section of my GitHub Pages repository (jasoneckert/jasoneckert.github.io). Plus, you can choose to add a comment section to other pages of your website if you modify the appropriate HTML component to include giscus.html as described in step 6.