Support Comments for Static Hugo Website

2020 12 02 head

There are times in software when you are facing a problem, you find an off-the-shelf solution, and a few lines of code later it just works.

Today I lived one of those moments.

The whole configuration of comments and modification of the Docsy theme took around one hour.


I wanted to add a comment section to this blog for a while. I was reluctant to implement one myself the classical way, using an external service such as disqus. This blog is a static website created with Hugo and does not use a database. All pages are written with Asciidoc, stored in a Git repository and rendered using Hugo. I wanted to store comments in a personally owned repository and protect my readers from an advertisement and personal information collection.

Meeting Utterances

Some information on the Internet about is wrong. Facts are:

  • The Utterances library uses a GitHub repository to store comments associated with your website articles and pages.

  • Your website can be hosted anywhere. You do not need to host your static website repository on GitHub, but you can.

  • Readers wanting to comment must login once with their GitHub account to authorize the application. Anonymous commenting is not supported. This restriction is reasonable for a technical website whose readers are technically affine and already have a GitHub account.

  • Utterance products are free. It claims to have no tracking, no advertisement, and no lock-in. The comments are stored in your repository as GitHub issues.

  • Utterances layout looks nice and can be styled.

Utterances is an open source app built and maintained by Jeremy Danyow. He announced the project in 2018. It provides a lightweight web widget <iframe> to add a comment section to a website.

When someone posts a comment, the Utterances bot literally leaves a corresponding comment on the issue. In other words, each page gets its own issue with a comment feed, and so you benefit from the entire feature set of issues out-of-the-box.

  • Comments are stored as issues inside a GitHub repository of your choosing.

  • You can edit, report and delete comments. These functions are great for moderation.

  • If you are watching the repository, you will get email notifications when comments are posted to your site.

The other wonderful aspect of Utterances is how simple the entire setup really is.

Setting Up Utterances

The process is described in details on The steps are:

  1. Create a public GitHub repository.

  2. Install the app on the repo you would like to host comments on. You can use the repository of your blog, or set up a dedicated repository. This option means your blog or website does not need to be hosted on GitHub.

  3. Configure the code snippet on the website and copy it.

You can skip the code snippet step if you are using Docsy and follow the below instructions to configure your theme.

  repo="<OWNER>/<NAME>" (1)
1 <OWNER>/<NAME> is the name of your repository. In my case, it would be marcelbaumann/tangly-team-comments.

Configure Docsy Theme

I use the Hugo theme Docsy to style the Open Source Components. I put some effort to have a configurable extension through site parameters.

Create the comments partial for utterances

The partial file contains the code to display for commenting using utterances. It is a modified version of the snippet you can generate on the website.

Create a partial in docsy/layout/partial. I named my partial comments-utterances.html and add the following snippet.

<div class="page-blank">
    <div id="utterancers_thread"></div>
    <script src=""
            repo= {{ .Site.Params.comments_utterances_repo }}                   (1)
            issue-term= {{ .Site.Params.comments_utterances_issue_term }}       (2)
            theme= {{ .Site.Params.comments_utterances_theme }}                 (3)
1 GitHub repository where the issues are stored
2 See documentation how the reference to a page, or an article can be tailored
3 See documentation about supported themes

Edit the blog content file

The template docsy/layouts/blog/content.html is edited to include the above defined partial file. The original file supports connecting to disqus. I replaced the disqus specific code with the inclusion of the partial defined above for utterances comment support. Perhaps Docsy will introduce a more generic mechanism in the future to integrate commenting systems. I assume they are waiting on Hugo to first provide such a mechanism. Currently, Hugo and Docsy only provide out of the box support for Disqus.

<div class="td-content">
	<h1>{{ .Title }}</h1>
	{{ with .Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
	<div class="td-byline mb-4">
		{{ with }}{{ T "post_byline_by" }} <b>{{ . | markdownify }}</b> |{{ end}}
		<time datetime="{{  $.Date.Format "2006-01-02" }}" class="text-muted">{{ $.Date.Format $.Site.Params.time_format_blog  }}</time>
	{{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) }}
	    {{ partial "reading-time.html" . }}
	{{ end }}
	{{ .Content }}
	{{ if (.Site.Params.comments_utterances) }}
		<br />
		{{ partial "comments-utterances.html" . }}
		<br />
	{{ end }}

	{{ partial "pager.html" . }}

Add four site variables to config.toml

The above changes try to be generic and are configured through site variables in the site configuration file under the [params] block. You do not need to edit partial files to tailor them.

# flag indicating if the utterances ( should be displayed
comments_utterances = true

# GitHub repository name where all comments are stored. The repository can be the same as the website repository or a different one.
comments_utterances_repo = "marcelbaumann/tangly-team-comments"

# Encoding used to map a site page to a GitHub issue. See utterances ( documentation.
comments_utterances_issue_term = "pathname"

# Theme used by utterance on the website. See utterances ( documentation.
comments_utterances_theme = "github-light"