Free Comments via GitHub Discussions

Scroll to the bottom of this post and you'll find a comments section. That shouldn't be possible: this is a static site, a folder of HTML files with no server, no database, nowhere to put a comment. The trick is a wonderful little disguise: every comment thread on this blog is a GitHub Discussion, courtesy of a small open-source tool called giscus. This post details what it is, its setup, and its trade-offs, as part of the series on how this site is built.

How it works

My blog's repository has Discussions enabled, with a category set aside for comments. When you visit a post, a script builds the comments section and giscus looks up a discussion whose title matches the page's path: for this post, /blog/free-comments-via-github-discussions.html. If someone has commented before, the thread exists and gets displayed. If nobody has, giscus shows an empty comment box, and the discussion is created automatically the first time someone posts.

Commenting requires a GitHub account, which is the design's biggest filter and, depending on your audience, either a bug or a feature. For a blog like mine, whose readers skew technical, it's mostly a feature: sign-in deters drive-by spam so effectively that I do no spam moderation at all. For a blog aimed at a general audience it wouldn't be the best solution, and something like a hosted comments service (or no comments, with an email link) might fit better.

The setup

Enable Discussions on the repository (a checkbox in settings) and create a category for comments; giscus recommends the Announcements type, so that only the widget and maintainers can open new threads, keeping the category from becoming a second inbox. Install the giscus app on the repository from GitHub's app directory. Then the giscus website generates your embed code: you tell it the repository, category, and how pages should map to discussions (I use the page path), and it produces a script tag with everything encoded as attributes.

Most sites paste that script tag into their template and are done. Mine goes through the shared components file, which builds it dynamically on every post page. Ez pz.

The details

Matching the site's theme. giscus ships with stock light and dark themes, but it also accepts a custom stylesheet URL, so this site serves its own giscus-dark.css and giscus-light.css and the comments render like part of the page rather than a bolted-on box. The fiddly bit is the theme toggle: when you switch the site between dark and light, a message gets posted into the giscus iframe telling it to swap stylesheets too, so the comments change theme in step with everything around them.

Lazy loading. The widget loads only when you scroll near it, so readers who never reach the bottom never fetch it. Comments are the last thing on the page both location wise and in load time!

A refresh button. The embed is static once loaded: if someone comments while you have the page open, nothing updates. A small refresh control re-mounts the widget on demand.

The trade-offs

If GitHub discontinued Discussions, or giscus vanished, my comment sections would go blank (the data would survive, in the discussions themselves, and giscus being open source means it could be self-hosted). Comments also don't work offline, and they're invisible to readers with JavaScript off; my offline post covers why the service worker deliberately leaves them alone. This is fine for a personal blog: comments are a nice-to-have on top of the writing, not the point of it.

What's nice is there are no ads injected next to your readers' words, no tracking scripts profiling them, no database to secure, and moderation through tools (GitHub's) that are already set up and hosted for you. The comparison is with Disqus, the long-time default, is pretty clear: disqus is filled with ads, and filled with tracking scripts etc. I know which one I prefer!