Utterances — Lightweight Comments Widget Built on GitHub Issues

Introduction

Utterances is a comments widget that stores comments as GitHub Issues. When a visitor comments on your page, utterances creates or appends to a GitHub Issue mapped to that page. Commenters authenticate with their GitHub account, so there is no separate user system, no database, and no tracking scripts. It is ideal for developer blogs and documentation sites.

What Utterances Does

• Embeds a comment section on any webpage using a single script tag
• Maps pages to GitHub Issues using pathname, URL, title, or a custom term
• Renders comments with full GitHub-flavored Markdown support including code blocks
• Loads and posts comments via the GitHub API with OAuth authentication
• Supports light and dark themes matching GitHub's own styling

Architecture Overview

Utterances consists of a small client-side script that renders an iframe on your page and a lightweight server component hosted at utteranc.es. When the widget loads, it queries the GitHub API for an Issue matching the configured term. If found, it displays existing comments in the iframe. When a user posts a comment, the server uses a GitHub App token to create the comment on the Issue. All data lives in your GitHub repository as standard Issues.

Self-Hosting & Configuration

• Add the script tag to your page with repo set to your GitHub repository
• Install the utterances GitHub App on the target repository to grant comment permissions
• Choose an issue-term mapping strategy: pathname, url, title, og:title, or a specific issue number
• Select a theme from built-in options like github-light, github-dark, preferred-color-scheme, and others
• Self-host the server component by deploying the utterances API from the repository if you want full control

Key Features

• No tracking, no ads, and no paywall; comments are plain GitHub Issues
• GitHub-flavored Markdown rendering with syntax highlighting in comments
• Automatic Issue creation when the first comment is posted on a new page
• Reactions support inherited from GitHub Issues (thumbs up, heart, etc.)
• Minimal footprint with no external CSS or JavaScript dependencies beyond the single script

Comparison with Similar Tools

• Giscus — uses GitHub Discussions instead of Issues, supporting threaded replies and more reaction types; utterances uses the simpler Issues model
• Disqus — full-featured commercial platform with ads and tracking; utterances is free, ad-free, and privacy-respecting
• Commento — self-hosted privacy-focused comments with its own database; utterances needs no database and leverages GitHub
• Cusdis — lightweight open-source alternative with email notifications; utterances benefits from GitHub's existing notification system

FAQ

Q: Do commenters need a GitHub account? A: Yes. Comments are posted via GitHub OAuth, so commenters must have a GitHub account. This works well for developer-oriented sites.

Q: Can I moderate comments? A: Yes. Comments are GitHub Issues, so you can edit, delete, lock, or hide them using standard GitHub moderation tools.

Q: Does utterances work with private repositories? A: No. The repository must be public for the widget to read and display comments without authentication barriers.

Q: Will utterances clutter my repository Issues? A: Comments are labeled with a configurable label (default: utterances) so you can filter them in the Issues tab.

Sources

• https://github.com/utterance/utterances
• https://utteranc.es