Setting up Github comments on your blog with Utterances

Posted on August 28, 2022  •  4 minutes  • 662 words

I’ve been steadily migrating articles over from my old blogs over the past couple of weeks. It’s been a great excuse to look at some new (at least new to me) blog technologies and techniques. This one I like so much I thought I would share it with you all, and it’s a nice break from the older content I’ve been sifting through. This blog article is about how to use GitHub’s technology on your very own blog or website!

Utterances

The folks at Utterances have figured out that you can use GitHub’s APIs to create a comment platform for your own blog or website. It all works on GitHub issues, which means you get to benefit from some of the built-in features of GitHub without using an untrusted 3rd party or having to tolerate ads. Each page of your blog or website gets its own GitHub Issue as people comment on them, and subsequent comments are added in the same way as replies to GitHub issues.

Commenters will need to have a GitHub account, but for tech blogs like this, I’d hazard a guess that 99% of its readers will already have one. I flirted with the idea of implementing Disqus (I actually did implement Disqus, and immediately removed it because of its tracking cookies and adverts) but this feels like a much more elegant solution. It’s open source too which is awesome.

Getting set up

1. First of all create yourself a new GitHub repository and leave it public. It needs to remain public because that’s how your commenters will be able to comment. Utterances only works with repositories on the github.io domain, and to get one of those you’ll need to create it as if you’re using GitHub Pages.

   1a. Name the new repository like so <repository name>.github.io. If you’ve not done this it’s a bit strange looking at first. If you’re still not sure, you can see the one for this blog here.

   1b. Once you’ve created your repository in this way, you should now see your page published under a github.io address. If it’s not yet published, publish it. If you click Visit site you’ll be taken to your new page. This is the URL you’ll use with Utterances.

2. Install the Utterances app to GitHub.
   You only need to grant access to your new repository, so just select that, unless you’re going to enabled it on multiple websites.
   

3. Replace the value of the repository variable below (line 2) with your new github.io address.

1  <script src="https://utteranc.es/client.js"
2    repo="<your github username>/<repository name>.github.io"
3    issue-term="pathname"
4    label="<your-custom-label>"
5    theme="dark-blue"
6    crossorigin="anonymous"
7    async>
8  </script>

Tip 🚀

Don’t include http/https in the repository address or you’ll get a repo invalid error.

Colour themes

You can choose from the following colour themes:

• github-light
• github-dark
• preferred-color-scheme
• github-dark-orange
• icy-dark
• dark-blue
• gruvbox-dark
• photon-dark
• boxy-light

You can further configure your experience on the Utterances read-me, and even make a test comment there

4. Next, you can now cut and paste the code into your site where you want the comments block to appear. This blog is currently using Hugo, and the theme I’m running contains a partial for blog pages. For me, this was the perfect place for blog article comments and it was on the following path:

1layouts/_default/single.html

You can see on this article where this ends up being when the site renders at the footer of the page. Here’s the file with some extra context:

 1
 2    {{ .Content }}
 3  </article>
 4
 5  <script src="https://utteranc.es/client.js"
 6    repo="<your github username>/<repository name>.github.io"
 7    issue-term="pathname"
 8    label="<your-custom-label>"
 9    theme="dark-blue"
10    crossorigin="anonymous"
11    async>
12  </script>
13
14  {{- partial "social.html" . -}}

Deleting Comments

Occasionally you’ll want to delete comments, such as when someone posts something which violates your policies, or to tidy up tests. Fortunately you can manage comments in the exact same way as your GitHub issues. Simply delete the comment in your GitHub repository.

Sorted! :thumbs_up: