Adding comments system to a Hugo site using Giscus

Introduction

My previous theme had several comment options built in. One of which was gitalk and so my previous post on this found setting it up super simple. However, I went and saw a new theme I liked and migrated to it in 2022. This theme only supported Discus and I am not really a fan of it. So comments have been disabled for a while.

Looking for an option, I stumbled across this excellent blog post which details several options for implementing comments on static sites. After a quick review, I have chosen to explore Giscus since it has a really easy configuration approach.

My community are devs, they typically will use github and so I quite like the option of a github based commenting system as folks will need to have a github account to comment. In the future I may consider something more open, but I don’t really have much traffic, so comments are likely to be low. This option is the most suitable for me right now.

Create a repository

Initial steps are;

• Create a public repository to hold your comments. I have created mine previously, there is a how to here .
• Enable the discussions feature, github guide can be found here .
• Install the giscus app by clicking this link.

I have restricted giscus to only access the specific repository I created for comments;

With those steps out of the way, I can test whether giscus can access the repository directly from their site;

Now that I have proved that giscus can talk to my repository, I can get on with the rest of the configuration.

Configure giscus codeblock

The giscus site allows me to configure how I want to render the comment block and then returns the necessary code. I won’t go through every option, but once you have completed your choices, you can copy the script block. Mine looks like this;

<script src="https://giscus.app/client.js"
        data-repo="justinjbird/site-blog-comments"
        data-repo-id="MDEwOlJlcG9zaXRvcnkzNDY2NTAzMzE="
        data-category="General"
        data-category-id="DIC_kwDOFKl2284CWeue"
        data-mapping="pathname"
        data-strict="1"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="en"
        crossorigin="anonymous"
        async>
</script>

I could technically paste this into the footer partial for my posts, but I want to allow things to be configured at the site level and have the ability to turn comments off on a specific post if I want to. First, I will set up the partial for my new code block, then go through making it a bit more dynamic.

Create partials

Hugo handles content by checking site directories first, then appending it with content from the theme directories. If a file is found in both locations, it will prioritise the site version. I need to amend the footer partial so I will make a copy of the theme version and save it at the site level. The footer partial can be found at this path for my theme;

./themes/hugo-clarity/layouts/partials/footer.html

Because I am going to override the default behaviour, I will take a copy of this and save it in the site partials folder at this path;

./layouts/partials/footer.html

Why not amend the file where it is? Because Hugo will prioritise a site file, so any changes I make will take precedence. I can make changes to the file knowing that the default is available to revert to, plus if I take newer published versions of the theme I won’t run into issues with my custom file getting overwritten.

I also want a partial for the giscus code block above. So in the site partials directory, I want to create a giscus.html file.

Populate the giscus partial

In my giscus partial I have pasted the codeblock provided by giscus and have templated it to allow me to add some control through my site. My completed partial looks like this;

{{- if (eq (.Site.Params.disableComments | default false) false) -}}
    {{- if (eq (.Params.disableComments | default false) false) -}}
        <script src="https://giscus.app/client.js"
            data-repo="justinjbird/site-blog-comments"
            data-repo-id="MDEwOlJlcG9zaXRvcnkzNDY2NTAzMzE="
            data-category="General"
            data-category-id="DIC_kwDOFKl2284CWeue"
            data-mapping="pathname"
            data-strict="1"
            data-reactions-enabled="1"
            data-emit-metadata="0"
            data-input-position="bottom"
            data-theme="{{ .Site.Params.giscusTheme }}"
            data-lang="en"
            data-loading="lazy"
            crossorigin="anonymous"
            async>
        </script>
    {{- end -}}
{{- end -}}

There are two if statements that will control whether the comment block will appear on the page. The first if statement checks the disableComments parameter in the site’s parameter file, the second line checks the disableComments parameter in the page’s front matter. If both parameters equal false, the script will be run. Furthermore, with the default option being there if the parameter doesn’t exist it will return false. This allows me to turn off comments on a specific page but also completely disable comments across the site if I want to.

The second change I have made is to turn the theme option into a parameter check. This is just a preference thing - it will mean that I can adjust this setting from my param file rather than making changes to partial files. I could configure more of the options this way, but I don’t see me adjusting those settings once I have set them.

Update footer partial

I need to add a partial call in my footer partial to grab my configured giscus code. My footer partial already has a lot of code in it, so I need to decide where it needs to go. I can see that the footer class creates the bar at the bottom of my posts, so my partial call should go just above that. The code I need to add is;

{{ partial "giscus" . }}

This will add the code from the giscus.html file into this partial. The important thing to note here is that “giscus” is the name of the file and since I have put the giscus file into the root of the partials directory along with the footer file, that is all I need to include. If I had stored the giscus file in a subdirectory then “giscus” would have needed to include that subdirectory (e.g. “subdirectory/giscus”).

My updated footer partial looks like this;

{{- $s := .Site.Params }}
{{ $t := .Site.Title }}
{{- if or .Params.enableMathNotation $s.enableMathNotation }}
  {{ partialCached "math" . }}
{{- end }}
{{- $iconsDir := default "icons/" .Site.Params.iconsDir }}
{{- $defaultFooterLogo := printf "%s%s" $iconsDir "apple-touch-icon.png"}}
{{ partial "giscus" . }}
<footer class="footer">
  <div class="footer_inner wrap pale">
    <img src=posts/2023/adding-comments-to-a-hugo-site-using-giscus/'{{ absURL (default $defaultFooterLogo $s.footerLogo) }}' class="icon icon_2 transparent" alt="{{ $t }}">
    <p>{{ T "copyright" | markdownify }}{{ with $s.since }}&nbsp;{{ . }}-{{ end }}&nbsp;<span class="year"></span>&nbsp;{{ upper $t }}. {{ T "all_rights" | markdownify }}</p>
    {{- partialCached "top" .}}
  </div>
</footer>

Bear in mind that this footer is specific to my site, you shouldn’t copy this code directly because it probably won’t work with your theme. You simply should be pasting the line {{ partial “giscus” . }} into your existing footer code on a new line at the appropriate place in the code. Remember you can move this line around and rebuild your site until it appears in the preferred place.

Build your site and check the comments

If everything works, I should now be able to build my site and see if it has worked…

Adding the parameters

.Site.Params looks for parameters present in your configuration file. Where these appear depends on how your theme and how you have configured things. There are several places this could appear, if you don’t know about advanced configurations chances are these will only be present in a file called config.toml at the root of your site.

If you have a more advanced configuration, then I am going to assume that you created it and so you know what you are doing so this explanation will focus on amending the config.toml file. If your config and params have been separated or moved to the config directory, then you’ll need to update the appropriate file.

If I open my config.toml file, I need to find a line that says [Params]. Any line under that will be a parameter that is being referenced using the notation .Site.Params. If no [Params] section exists, then I can add it to the end of the file. Underneath the [Params] line, I am going to add two parameters - one for disableComments and one for the giscusTheme parameter. The code should look like this (noting that you probably will have other parameters if [Params] was already present);

[Params]
giscusTheme="preferred_color_scheme"
disableComments=false

This will now allow me to adjust the giscus theme and site-wide comments directly from the config file. Updating disableComments=true would disable giscus on every page of the site. If I want to disable comments on a single page them I simply need to add disableComments=true to the front matter of that specific page and giscus will be disabled.

Time to Publish

Now that I have giscus running, I can publish my site! This will enable comments on my site, and folks can now comment so long as they are logged in using github. When a comment is added to a page, it will be posted as a discussion thread to the configured repository (which you can see here ). Each time a page is loaded it will grab the related discussion from the github repository and present them on the page. Pretty cool!

Summary

So with some minor Github configuration and with the help of Giscus’ super helpful configuration page, I have been able to reinstate comments on my site and it was super easy!