utteranc.es

To comment through the utterances widget, a visitor needs a GitHub account and must authorize the utterances app via GitHub OAuth so it can post on their behalf. As an alternative, they can skip the widget entirely and comment directly on the GitHub issue that backs the page. Both paths require a GitHub account; there is no anonymous or non-GitHub commenting option described.

The two commenting paths

1. Comment through the widget (OAuth)

When a visitor types into the comment box on your site, utterances triggers the GitHub OAuth flow. The visitor signs in to GitHub and grants the utterances app permission to post comments on their behalf. After that, their comment appears both in the widget and in the corresponding GitHub issue.

What the visitor experiences:

• A prompt to sign in to GitHub, or to authorize the utterances app if they are already signed in.
• A consent screen listing the permission being granted (posting on their behalf).
• Return to your page, where the comment is submitted.

2. Comment directly on the GitHub issue

Every page's comment thread is a GitHub issue. A visitor who prefers not to authorize the app can open that issue on GitHub and comment there with their normal GitHub account. The comment will show up in the widget the next time the thread loads, because the widget reads from the issue.

This path is useful for visitors who are cautious about granting OAuth permissions to third-party apps, or who are already browsing GitHub.

What happens on a page with no comments yet

The first commenter does not need to create anything manually. When utterances loads, it searches GitHub issues for one matching the page by url, pathname, or title. If no matching issue exists, utterances-bot creates one automatically the first time someone comments. So the visitor's only job is to authorize and post; issue creation is handled for them.

Requirements at a glance

Practical notes for site owners

• Expect a sign-in step. Visitors without a GitHub account cannot comment through the widget. If your audience is unlikely to have GitHub accounts, utterances may not fit; the site describes it as built on GitHub issues with no lock-in, and all data lives in GitHub issues.
• The OAuth prompt is the main friction point. Some visitors will abandon at the authorization screen. Offering a visible link to the underlying GitHub issue gives them a second route.
• Moderation happens on GitHub. Since comments are issues, you manage them with GitHub's own tools rather than a separate dashboard.
• No tracking or ads. The project states it uses no tracking and no ads and is always free, which is relevant if visitors ask what the authorization is used for: it is for posting comments, not for analytics.

Common sticking points

• "I commented but it didn't appear." If the visitor commented directly on GitHub, the widget may need a reload to pick up the new comment.
• "The sign-in page looks unfamiliar." It is GitHub's standard OAuth consent screen; the visitor is granting the utterances app permission to post on their behalf, not handing over their password.
• "There's no comment box." The widget only renders where the site owner has installed the script; if it is missing, commenting through the page is not possible, though the GitHub issue may still exist.

No. According to the utterances site, the widget has no tracking, no ads, and is always free. It also has no lock-in because all comment data is stored in GitHub issues rather than in a proprietary database. These conditions apply to the hosted utterances widget as described on its site; they are not a separate promise about GitHub itself or about any third-party analytics you might add to your own page.

What “no tracking, no ads, always free” covers

The site describes utterances as a lightweight comments widget built on GitHub issues and states three related properties:

• No tracking and no ads — the widget itself does not include analytics or advertising.
• Always free — the site presents the widget as free to use.
• Open source — the code is open source, so you can inspect what it does.

These are statements about the utterances widget. They do not describe GitHub's own data practices, and they do not prevent you from adding your own analytics elsewhere on your site.

Why there is no lock-in

The key mechanism is where comments live. When utterances loads, it uses the GitHub issue search API to find the issue associated with the page, based on url, pathname, or title. If no matching issue exists, utterances-bot creates one the first time someone comments.

Because every comment is a GitHub issue in your repository, the data is not held inside a separate commenting service. The site summarizes this as “No lock-in. All data stored in GitHub issues.” In practice, that means:

A concrete example

Suppose you run a blog post at a fixed URL and add the utterances script. A reader arrives and wants to comment. utterances searches GitHub issues for one matching that page. If none exists, the bot creates an issue on the first comment. The comment then appears both in the widget and as an issue in your repository.

If you later remove the widget, those issues still exist in GitHub. That is the practical meaning of “no lock-in”: the conversation is not trapped in a vendor's database.

What to check before relying on these claims

• Commenting requires GitHub authorization. To comment through the widget, users must authorize the utterances app to post on their behalf via the GitHub OAuth flow. Alternatively, they can comment on the GitHub issue directly. So “free” and “no tracking” do not mean “no account needed to comment.”
• Your repository settings matter. Because comments are issues, the visibility and permissions of your GitHub repository affect who can read and write comments.
• The claims are the site's own. The page states these properties; it does not publish a separate audit. If tracking or cost is a hard requirement, verify against the current site and your own setup rather than treating this as a guarantee about every deployment.

In short: utterances itself is presented as ad-free, tracking-free, free to use, and not lock-in, with the lock-in answer resting on comments being stored as GitHub issues in your repository.

utterances is a lightweight comments widget built on GitHub issues, styled with Primer (the CSS toolkit that powers GitHub) and implemented in vanilla TypeScript. It supports light and dark themes, ships no font downloads, JavaScript frameworks, or polyfills for evergreen browsers, and stores all comment data in GitHub issues rather than a separate database.

How the Widget Works

When utterances loads on a page, it calls the GitHub issue search API to find the issue associated with that page. The match is made by url, pathname, or title, depending on configuration. If no matching issue exists, nothing breaks: the utterances-bot creates the issue automatically the first time someone comments.

To post a comment through the widget, a visitor must authorize the utterances app via GitHub's OAuth flow so the app can post on their behalf. Alternatively, anyone can comment directly on the corresponding GitHub issue.

Design Characteristics

The Primer styling means the widget visually matches GitHub's interface, which keeps it coherent on developer blogs and documentation sites. The absence of tracking and ads is a stated design property of the project, not an optional setting.

Technical Characteristics

• Vanilla TypeScript. The widget is written in plain TypeScript with no JavaScript framework dependency.
• No font downloads. The widget does not fetch web fonts, so it adds no font-related network requests to the host page.
• No polyfills for evergreen browsers. The project targets modern browsers and does not ship compatibility shims for them.
• GitHub as the backend. Comments are GitHub issues; there is no separate comment database to host or maintain.
• Automatic issue creation. The utterances-bot creates the issue on first comment, so page authors do not need to pre-create issues per page.

What This Means in Practice

For a site owner, the practical effect is a small embed that inherits GitHub's look, offers a dark theme, and keeps comment data in a repository you control. For readers, commenting requires a GitHub account and an OAuth authorization step, or commenting on the issue directly on GitHub.

The project lists sites using utterances including Haxe documentation and cookbook, sadsloth.net, and danyow.net. If you use it, the project asks that you add the utterances topic to your repo.

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:

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.

utterances finds the GitHub issue for a page by running a GitHub issue search when the widget loads, using one of three page identifiers you choose during setup: the full url, the pathname, or the page title. If no matching issue exists, nothing breaks — the utterances-bot creates one the first time someone comments. This applies to any page where you embed the widget and have configured a repository and a mapping option.

The matching flow

1. You pick the identifier at configuration time

The widget needs to know which piece of page data to search on. utterances supports three options:

The choice is part of the embed configuration, so it is fixed per site (or per widget instance) rather than decided at runtime by the reader.

2. On load, the search API runs

When the utterances script initializes, it queries the GitHub issue search API for an issue in your configured repository that corresponds to the selected identifier. The result is the issue whose comments become the widget's comment thread.

3. No match is not an error

If the search returns nothing — a brand-new post, for example — the widget simply shows an empty thread. The issue is not created at page load; it is created lazily.

4. First comment creates the issue

The first time a reader submits a comment, utterances-bot opens an issue in your repository for that page. From then on, the same identifier resolves to that issue, and all subsequent comments land there.

Why the identifier choice matters

The identifier is effectively the join key between a page and an issue. Two consequences follow:

• Changing the mapping later orphans threads. If you switch from pathname to title, existing issues were created under the old key and will no longer be found, so old comments appear to vanish from the page (they still exist in the repository).
• Collisions are possible. Two pages that share a title (common with generic titles like "Home" or "Archive") will map to the same issue and share one comment thread. pathname or url avoids this when paths are unique.

A practical example: a docs site with pages at /docs/install and /docs/config is safe with pathname, because each path is distinct. A blog where every post is titled with the post name is also safe with title, but a blog with a shared suffix in titles is not.

Commenting and authorization

To post through the widget, a reader must authorize the utterances app via the GitHub OAuth flow so it can post on their behalf. Readers who prefer not to authorize can comment directly on the GitHub issue itself, and those comments appear in the widget because the widget reads the same issue thread.

What this design implies for you

• Your repository is the database. All comment data lives in GitHub issues, so moderation, search, and export happen through GitHub's own tools.
• The widget is read-mostly until first comment. Loading a page performs a search; it does not create issues, so empty threads cost you nothing in repository clutter until someone actually engages.
• Plan the identifier before launch. Pick pathname when paths are stable and unique; pick url when you need strict per-URL threads; pick title only when titles are reliably unique and URLs are not.

The site lists real deployments such as Haxe documentation and cookbook, sadsloth.net, and danyow.net, which is a reasonable signal that the pathname/url approach holds up across documentation and personal blog structures.