Setting up Utterances on Blogdown

January 7, 2022

howto

R, blogdown, utterances, blog, comments, Hugo

I like the idea of engaging with visitors here. It’s a reliable way to gather feedback and it really bring a static post to life.

The most common and streamlined way to do so is with an on-page commenting system.

And so began my quest to implement a commenting system on this site.

Begone, Disqus #

There are a whole bunch of commenting systems out there. One of the most popular is Disqus.

When I first started this site, I did give Disqus a chance.

But once had Disqus set up and started testing it out, I discovered that it loaded all sorts of unwanted ads onto my pages. In the background, it was also collecting a whole bunch of data.

That was a dealbreaker for me. I promptly reverted my changes and decided that I was better off with no comment system at all than with Disqus.

Utterances #

I took my time looking for an alternative system. While browsing a bunch of blogs built around the Apéro theme (the theme that this site is currently built on), I noticed that a lot of them had a strikingly clean and common commenting system. It bore a strong resemblance to Github issues.

After some light investigation, I found that all these Apéro-users were using Utterances for their commenting.

There was a lot to like about it, especially:

Open source. 🙌
No tracking, no ads, always free. 📡🚫
No lock-in. All data stored in GitHub issues. 🔓

With that, the decision became clear: Utterances would be the way to implement commenting on this site.

Figuring things out #

The guidance provided on the main Utterances site was pretty generic and wasn’t very tailored to Blogdown sites. Fortunately, I didn’t have to figure out how to integrate Utterances with Blogdown from scratch. There were a whole bunch of posts out there that covered the topic already, and I just followed along and made some slight modifications along the way.

The site repo does not have to be public #

The first instruction provided on the Utterances page states:

Make sure the repo is public, otherwise your readers will not be able to view the issues/comments.

I wasn’t a big fan of making the source code of my blog public. I have a lot of junk in there, and I’m not ready to burden the world with that mess quite yet. Someday, maybe. For now, sorry.

While searching for some guidance, I did find a post on Migrating from Disqus to Utterances by Nan Xiao. In it, he mentions, “Check out the utterances docs to set up a GitHub repo with the utterances app installed for storing the comments in issues. I created a dedicated new repo for this.”

So while the Utterances instruction does mention that a repo has to be public for the comments to be viewable, it seems that the repo that will track comments doesn’t have to be the site repo itself.

I decided to create a separate public repository, kwanlin/kwanBlog-comments, with the sole purpose of tracking Utterances comments.

Install Utterances on Github #

For Utterances to work, it needs to be installed on each repository that will interact with it.

Log into your Github account, and follow along with the directions to either install Utterances on all repositories or on only select repositories that will use Utterances.

I opted for the latter. I installed Utterances to my site’s repository, as well as the kwanBlog-comments repository to which comments would eventually be linked.

Configure config.yaml/config.toml #

Blogdown sites include a config.yaml or config.toml file, which handles site-wide configurations.

Within the Apéro theme’s config file, there are some stubs in place to handle Utterances. This makes setting up Utterances immensely easier.

  # Configuration of https://utteranc.es/ for comments
  [params.utterances]
    use_utterances = true
    repo_name = "hugo-apero/apero"
    issue_term = "pathname" # url, pathname, or title
    theme = "boxy-light"
    label = "comments :crystal_ball:"

Just modify the parameters to suit your needs. In my case, my Utterances config.yaml looks like this:

  utterances:
    issue_term: pathname
    label: 'comments'
    repo_name: kwanlin/kwanBlog-comments
    theme: boxy-light
    use_utterances: yes

Note that repo_name points at the Github repository where comments will be stored.

Configure _index.md #

Just changing the config file alone wasn’t sufficient to get Utterances to show up.

After some head-scratching, I decided to examine the source code of some Apéro-themed sites that did have Utterances set up.

$ grep -ir "utterances" .
./content/publication/_index.md:  show_comments: false # see site config to choose Disqus or Utterances
./content/blog/_index.md:  show_comments: true # see site config to choose Disqus or Utterances
./content/project/_index.md:  show_comments: false # see site config to choose Disqus or Utterances
./content/talk/_index.md:  show_comments: false # see site config to choose Disqus or Utterances
./config.toml:disqusShortname = "" # see params.utterances to use utterances instead of Disqus
./config.toml:  [params.utterances]
./config.toml:    use_utterances = true
...

It seems that the piece I was missing was that the ./content/.../_index.md files had to be modified so that show_comments was set to true for commenting to appear.

Once that change was made and the code was pushed… success!

The steps, in brief #

Assuming you’re using Blogdown and the Apéro theme (other themes will work too, it just might take a few more steps):

Set up a public Github repository to track comments
Install Utterances to your Github repositories
Modify config.yaml or config.toml
Set show_comments: true in the _index.md for sections where comments should be available

And that’s it!

Moderate at will #

One final thing: as the repository owner, you are able to moderate comments through the Issues section in the repository that tracks the site’s comments.

Conclusion #

With that done, this site now includes a lightweight, non-invasive commenting system that selectively appears in sections that I so choose.

In the words of Professor Hulk from Avengers: Endgame, “I see this as an absolute win!”

Resources #

Here are some especially handy resources I found in my quest to figure out Blogdown + Apéro + Utterances.