What Is utterances and What Is It Used For?

Updated

utterances is a lightweight, open-source comment widget that stores comments as GitHub issues. It is designed for blog posts, wiki pages, documentation, and similar static sites where you want reader discussion without running a separate comment database. According to the project site, it has no tracking, no ads, and is always free, with all comment data kept in GitHub issues rather than a third-party service.

How It Works

When the widget loads, it uses the GitHub issue search API to find the issue associated with the current page. The match is based on one of three identifiers:

  • url — the full page URL
  • pathname — the URL path
  • title — the page title

If no matching issue exists, nothing breaks. The utterances-bot automatically creates an issue the first time someone comments on that page.

To leave a comment through the widget, a user must authorize the utterances app to post on their behalf via the GitHub OAuth flow. Alternatively, they can comment directly on the corresponding GitHub issue.

What It Is Used For

utterances fits sites that already live in a GitHub-centric workflow. The project lists these use cases and examples:

Use case Example from the project
Blog comments sadsloth.net, danyow.net
Wiki pages —
Documentation and cookbooks Haxe documentation and cookbook

The common thread is static or GitHub-hosted content: if your pages are generated from a repository and you want comments to live alongside that repository's issues, utterances keeps everything in one place.

Key Properties

  • No lock-in. All data is stored in GitHub issues, so comments remain accessible through GitHub even if you remove the widget.
  • No tracking or ads. The project states this explicitly.
  • Styled with Primer. It uses the CSS toolkit that powers GitHub, and includes a dark theme.
  • Lightweight. Built in vanilla TypeScript, with no font downloads, JavaScript frameworks, or polyfills for evergreen browsers.

When It Makes Sense — and When It Doesn't

utterances is a good fit if your audience is comfortable with GitHub accounts and you want comment data to stay in a repository you control. It is a poor fit if you need anonymous commenting, non-GitHub login options, or comment storage outside GitHub — the OAuth requirement means every commenter needs a GitHub identity.

To try it, the project provides a live demo linked from its homepage, and sites using it are encouraged to add the utterances topic to their repository.