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.
Some information on the Internet about utteranc.es 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 utteranc.es 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.
The process is described in details on utteranc.es. The steps are:
Create a public GitHub repository.
Install the utteranc.es 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.
Configure the code snippet on the utteranc.es 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. |
<script
async
src="https://utteranc.es/client.js"
repo="<OWNER>/<NAME>" (1)
issue-term="title"
theme="github-light"
crossorigin="anonymous"
</script>| 1 | <OWNER>/<NAME> is the name of your repository. In my case, it would be marcelbaumann/tangly-team-comments. |
I use the Hugo theme Docsy to style the Open Source Components. I put some effort to have a configurable extension through site parameters.
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 utteranc.es website.
Create a partial in docsy/layout/partial. I named my partial comments-utterances.html and added the following snippet.
<div class="page-blank">
<div id="utterancers_thread"></div>
<script src="https://utteranc.es/client.js"
repo= {{ .Site.Params.comments_utterances_repo }} (1)
issue-term= {{ .Site.Params.comments_utterances_issue_term }} (2)
theme= {{ .Site.Params.comments_utterances_theme }} (3)
crossorigin="anonymous"
async>
</script>
</div>| 1 | GitHub repository where the issues are stored |
| 2 | See utteranc.es documentation how the reference to a page, or an article can be tailored |
| 3 | See utteranc.es documentation about supported themes |
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 .Params.author }}{{ 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>
</div>
{{ 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" . }}
</div>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 (https://utteranc.es/) 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 (https://utteranc.es/) documentation.
comments_utterances_issue_term = "pathname"
# Theme used by utterance on the website. See utterances (https://utteranc.es/) documentation.
comments_utterances_theme = "github-light"[1] Static Website Improvements Marcel Baumann. 2023.
[2] Improving a Static Website Build With Hugo and Docsy Marcel Baumann. 2021.
[3] Support Comments for Static Hugo Website Marcel Baumann. 2020.
[4] Creating a technical Website with Hugo and Asciidoc Marcel Baumann. 2020.