Backend-free Comments and Community

There are only three ways to add comments to a static site, and picking wrong is a long regret.

| Approach | How it works | Pros | Cons |
|---|---|---|---|
| Giscus | Backed by GitHub Discussions | Free, no ads, good Markdown support, data lives in your own repo | Readers need a GitHub account |
| Waline | Self-hosted (Vercel plus a database) | Anonymous comments, customisable, has an admin panel | You maintain a service and a database |
| Disqus and similar | Third-party hosted | Quick integration, anonymous comments | Ads, slow, unreliable in some regions |

How to choose:

• Technical site, readers have GitHub accounts → Giscus, the default and least to maintain
• General audience, anonymous comments required → Waline
• Just want to try it → Disqus, ads accepted

What this site does, for reference: the main site deliberately has no comment box, and discussion goes to one external place instead. Concentrated discussion builds more atmosphere than comments scattered across pages, and there's nothing to moderate. Whether you add comments depends on what you're trying to accumulate.

Compliance note: a site carrying user-generated content needs a moderation process and a reporting path. Using a third-party comment service doesn't remove that responsibility.

Giscus in three steps:

1. Enable Discussions on the repo: GitHub repo → Settings → tick Discussions (the repo must be public)
2. Install the Giscus app: authorise it at giscus.app, scoped to the target repo only
3. Generate the snippet: enter the repo name at giscus.app, pick the mapping (pathname recommended) and copy the <script>

Drop it into the page, at the bottom of an article:

<div id="comments"></div>
<script src="https://giscus.app/client.js"
  data-repo="youruser/yourrepo"
  data-repo-id="R_xxxx"
  data-category="Announcements"
  data-category-id="DIC_xxxx"
  data-mapping="pathname"
  data-theme="preferred_color_scheme"
  data-lang="en"
  crossorigin="anonymous" async>
</script>

Lazy load it, strongly recommended: the comment box sits at the bottom of the page, so it must not slow down first paint. Use an IntersectionObserver and insert the script once the reader scrolls down.

Dark mode: data-theme="preferred_color_scheme" follows the system setting.

Verify: open the page in a different browser, not signed in to GitHub, and confirm you see a sign-in prompt rather than an error.

The value of a comment section isn't only interaction — good Q&A is itself searchable content. Plenty of people search an error message and find the answer in a comment.

Three tactics:

1. Promote repeated questions into the body: anything asked more than twice in the comments gets added to the article itself, and you reply to the commenter. This is the best source of content iteration there is
2. A "recent comments" module on the home or article page, so new visitors can see that people actually talk here
3. Make a comment page indexable: with Giscus the comments live on GitHub and the site only embeds them. If you want them indexed under your own domain, build a display page — sync comments into a static JSON and render that

Mind the weight distribution: comment quality varies, so keep it away from the page's main headings. Body first, comments after, hierarchy clear.

Moderation and atmosphere — this decides whether the section lives or dies:

• Deal with the first piece of spam the moment it appears, not once it's everywhere
• Pin a comment saying "search before asking, and include your environment" — it measurably lifts question quality
• Your own reply speed sets the tone. Answer the first 20 comments properly and people start answering for you

Don't: turn moderation off and then stop looking. By the time you check, the section is unusable.

The comment count is the emptiest metric there is. What you want to know is did comments make people stay, and did they come back.

Three events:

• comment_view: the comment box enters the viewport — how many people reach the bottom
• comment_click: clicking sign-in or the input — how many want to take part
• comment_submit: a comment is posted. Catch it with the widget's message event where you can; otherwise trust the Discussions side

Read them alongside what you already track:

| Symptom | Reading |
|---|---|
| High comment_view, very low comment_click | The barrier is too high (GitHub account) or the content didn't provoke a response |
| Lots of comments but dwell time unchanged | Interaction isn't turning into reading depth; the discussion may be shallow |
| Articles with comments have a clearly higher return rate | Comments are working; keep investing |

With Giscus in particular: the submit event happens inside an iframe, so trust the Discussions side for it and only record comment_view and comment_click on the front end. Don't hack a third-party iframe for the sake of a metric.

The decision: if after three months comment_click / comment_view is under 2%, your readers don't want a comment section — switch it off and put the effort back into content. That's exactly how this site decided, and discussion moved to one external place instead.

One more thing: write the event definitions into data/conversion.json, or whoever inherits this won't know where the numbers came from.