Posted inFOSS / HOWTO

HOW TO: Use GitHub issues to create a comments widget for your blog in 4 simple steps

Adding comments to your website/blog is a big deal. Functionality and price is a big factor. You’ll have to moderate the comments and fight spam. It’s a mess.

What if there was a free and open source project that would allow you use GitHub issues and create a comments widget that you can embed on any page in just a few simple steps?

Luckily there is one, and it’s called utterances.


  • Open source.
  • No tracking, no ads, always free.
  • No lock-in. All data stored in GitHub issues.
  • Styled with Primer, the css toolkit that powers GitHub.
  • Dark theme.
  • Lightweight. Vanilla TypeScript. No font downloads, JavaScript frameworks or polyfills for evergreen browsers.

How utterances works?

When Utterances loads, the GitHub issue search API is used to find the issue associated with the page based on url, pathname or title. If we cannot find an issue that matches the page, no problem, utterances-bot will automatically create an issue the first time someone comments.

To comment, users must authorize the utterances app to post on their behalf using the GitHub OAuth flow. Alternatively, users can comment on the GitHub issue directly.

How to install utterances?

1. Create a GitHub account if you don’t already have one.

2. Create a new repo and install the utterances app on the repo

NOTE: Make sure the repo is public, otherwise your readers will not be able to view the issues/comments. If your repo is a fork, navigate to its settings tab and confirm the issues feature is turned on.

3. Visit this link to customize your utterances instance. You can:

  • Choose the mapping between blog posts and GitHub issues.
  • Choose the label that will be assigned to issues created by Utterances.
  • Choose an Utterances theme that matches your blog.

4. Copy-paste the utterances script, with your prefferend customization, to your website where you want the commenting widget to be displayed.

For more info, check out the official project page on GitHub.