Right, let’s talk about turning your pristine, static website into a place where people can… well, talk. You could build a full-blown comment system yourself. You’d need a database, an API, authentication, spam protection, moderation tools—and about a week of your life you’d never get back. Or, you can be smart and let GitHub do the heavy lifting.

That’s the whole premise behind Utterances and its slicker successor, Giscus. They’re brilliantly simple: they treat your website’s comments section as a GitHub issue or discussion thread. A visitor leaves a comment on your site? It magically appears as a new issue or comment on a designated GitHub repo. It’s authentication handled by GitHub’s OAuth, content stored on GitHub’s servers, and moderation done through a platform you already know. It’s almost too clever.

How It Actually Works (The Magic Trick Explained)

Don’t just paste the script; understand the con. When you embed the Giscus script on your page, it does a few things. First, it looks for a specific data- attribute on its container to find your repo. Then, it uses GitHub’s GraphQL API to search for an issue or discussion whose title matches the current page’s URL or title.

If it finds one, it loads those comments. If it doesn’t, and a visitor leaves the first comment, the script uses the GitHub API to create that issue or discussion on the fly. This is the part that feels like magic. The user is prompted to authorize with GitHub (so they can post on behalf of their own account), and then their comment is posted both to your site and to the new GitHub issue. All the threading, editing, and reacting happens in near real-time.

Setting Up Giscus: A No-Nonsense Walkthrough

First, head over to giscus.app. This isn’t a shady third-party service; it’s just a fantastic configurator that generates the code for you. You’ll need to install the Giscus app on your GitHub repo (it asks for minimal permissions, basically just to read and write issues) and then configure the options.

The most important choice you’ll make is Discussions vs. Issues. Discussions are a bit more modern and are designed for, well, discussion. Issues are the classic workhorse. I prefer Discussions for comments because they feel more appropriate, but you can’t go wrong with either. The configurator will spit out a script tag for you. Here’s what one looks like:

<script src="https://giscus.app/client.js"
        data-repo="your-username/your-repo"
        data-repo-id="R_kgDOK...123"
        data-category="Announcements"
        data-category-id="DIC_kwDOK...456"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="en"
        crossorigin="anonymous"
        async>
</script>

Now, paste that into your site’s template where you want comments to appear. The data-mapping="pathname" is key—it means each unique page on your site (based on its URL) will map to a unique discussion thread. Use title if you prefer, but pathname is usually more reliable.

The Rough Edges and How to Sand Them Down

This isn’t all rainbows and serverless unicorns. There are trade-offs, and you need to know them.

  1. The GitHub Barrier: The biggest one. To comment, a user must have a GitHub account. This instantly excludes about 99.9% of the human population. This is perfect for a technical blog aimed at developers and a terrible idea for a recipe site for grandparents. Know your audience.

  2. The Blank Slate Problem: When a page loads for the first time and no one has commented yet, the Giscus box will be… empty. It can look a bit sad. You can mitigate this with a bit of clever CSS to style the initial state or a placeholder message.

  3. Caveats for Local Development: localhost:3000 is not a valid GitHub issue title. The script will fail gracefully (which is good) but silently (which can be confusing when you’re testing). You have two options: use the data-term attribute in your dev environment to point to an existing thread for testing, or just accept that comments only work on your live site. I do the latter; it’s simpler.

  4. Styling is a Suggestion: The theme is mostly out of your control. You get light, dark, and a few others. You can tweak it with CSS overrides, but it’s a bit of a fight. If pixel-perfect design is your thing, this will annoy you. If you just want functional comments, it’s fine.

The “Oh Crap, I Need to Moderate” Part

Here’s the best part: moderation happens where you already live—in GitHub. You can lock threads, delete inflammatory comments, mark replies as off-topic, and everything else the GitHub issue interface allows. You can even use GitHub’s saved replies for common responses. Spam is almost a non-issue because requiring a GitHub account raises the barrier to entry so high. It’s not just convenient; it’s genuinely effective.

So, is it perfect? No. But for a developer-centric site, it’s about as close as you can get without setting up a single server. It leverages the platforms you already use to solve a problem elegantly, and that’s the kind of cleverness I can always get behind.