Adding giscus Comments

#technology #zola

Ever since I rebuilt this site on Zola, one thing has been conspicuously missing: comments.

I've generally been unconcerned with their absence, and - being a static site - wasn't sure if it was practically achievable either.

giscus

giscus is a comments widget powered by GitHub Discussions. There are a few reasons why it's particularly well-suited for a static site:

  • No database: every comment is just a comment on a GitHub Discussion
  • No tracking, no ads, always free
  • Visitors can comment by authorising the giscus GitHub app (or just reply on GitHub directly)

The main downside: visitors need a GitHub account to comment.

Because it's purely client-side, it only needs a single <script> tag to be added to embed the comments directly on the site.

Getting it running

The first step happens on GitHub: create a public repository, install the giscus app on it, and enable Discussions.

Next, the configurator at giscus.app builds you a ready-made <script> tag that needs to be added to your site.

For this site I used the pathname mapping, which gives each page its own discussion. Since this is a multilingual site, the English and Chinese versions of a post get separate threads as a natural side effect. It's also possible to configure the mapping so both languages share a single thread.

There were a couple of small wrinkles to sort out in my minimal theme:

  1. The theme's page.html renders pages as well as posts. I gated the snippet behind a quick path check so giscus only appears under /posts/*.
  2. The generated snippet is hardcoded to English. I set it from the page's language so Chinese pages load zh-CN automatically.
  3. The site has a manual light/dark toggle, but giscus only tracks the OS prefers-color-scheme by default. A small bit of JS now pushes the current theme to the giscus <iframe> whenever the toggle changes.

Conclusion

Given how easy this was to set up, I'll leave comments running to see how it goes. Prior iterations of the site also had them, but they ultimately became more trouble than they were worth. We'll see how this 2026 experiment goes.

Comments