Migrating from Disqus to utterances

May 5th 2023 GitHub

I've been using Disqus as a comments engine on my blog since I switched to a statically generated site in 2015. Since then, I grew increasingly dissatisfied with it, primarily because of its unreliable notification system and complex administration panel.

I looked at some alternatives and finally chose utterances because of the following:

  • It can be embedded in a statically generated site.
  • It is completely free and without ads.
  • To post a comment, you log in with a GitHub account, which is a good fit for a technical blog like mine.
  • There is a tool available for importing comments from Disqus.

This post documents the steps I took to replace Disqus on my blog with utterances.

I first had to export existing comments from Disqus, following the official instructions. Fortunately, my site was small enough to have the export available, so I have soon received a mail with a download link. The downloaded gzip archive contained a 15 MB XML file with (hopefully) all comments from my site.

Next, I created a public GitHub repository for my comments and took a closer look at the import tool. It soon became obvious that I'll have to modify the code a bit to make it work for my scenario. So, I forked the repository and customized the code for my site as instructed. After creating a GitHub personal access token, I could finally run the tool. However, I encountered some issues during import that are worth mentioning:

  • For some reason, my Disqus export file contained a lot of threads without any posts. To make the import process faster, I changed the code to skip the URL validation for those threads, as there would be no import for them anyway.
  • Although the import tool uses delays between API request to not exceed the rate limits, I still encountered secondary rate limits a couple of times. In those cases, I waited for an hour or so and then continued with the import.

Once the import was complete, it was time to integrate utterances into my blog. After using the configuration UI, it was just a matter of replacing the old Disqus script element with the one generated. That was already enough to browse existing comments and even to add a new test comment to a post with existing comments.

However, I overlooked at first that I also have to install the utterances GitHub app in my repository. Without it, adding a comment to a post without previous comments and hence without a corresponding GitHub issue would fail. I think I lost a comment or two before I figured that out. Don't repeat my mistake.

Utterances is a great free open source comments engine that you can use on your site even if it's statically generated. To post comments, one needs a GitHub account. This makes it more suitable for sites with technical content, as their readers are more likely to already have an account and wouldn't have to create one just to post a comment.

Get notified when a new blog post is published (usually every Friday):

If you're looking for online one-on-one mentorship on a related topic, you can find me on Codementor.
If you need a team of experienced software engineers to help you with a project, contact us at Razum.
Creative Commons License