Hugo Comments Using GitHub Issues

Hugo
2 min read
Page content

Disqus-style comment SaaS is heavy for a static blog. Utterances stores each discussion as a GitHub Issue, loads a small client script, and authenticates with GitHub. DevOpsTales wires it through a partial and a per-post disable_comments flag.

Hugo

Prerequisites

  1. A public GitHub repository to hold issues (this site uses the Pages repo devopstales/devopstales.github.io).
  2. Install the Utterances GitHub App on that repository.
  3. Decide how issues are matched to pages. This site uses issue-term="url" so each permalink maps to one issue.

Issues are public. Do not enable comments on posts where that would be inappropriate.

The Utterances partial

layouts/partials/utteranc.html:

<script src="https://utteranc.es/client.js"
        repo="devopstales/devopstales.github.io"
        issue-term="url"
        label="utteranc"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

Useful knobs:

Attribute Role
repo owner/name where issues are created
issue-term url, pathname, title, or a specific issue number strategy
label Applied to new issues (create the label in the repo first)
theme github-light, github-dark, preferred-color-scheme, …

Gate comments in layouts

layouts/partials/comments.html:

{{- if .IsPage }}
{{- $disableComments := .Params.disable_comments | default false }}
{{- if not $disableComments }}
<div class="comments">
  {{- partial "utteranc.html" . -}}
</div>
{{- end }}
{{- end }}

layouts/_default/single.html includes that partial after the article body (near coffeebox / pager). Front matter on a normal post:

disable_comments: false

To turn comments off for one page:

disable_comments: true

Default in the partial is false, so omitting the key still shows Utterances. Set true explicitly on privacy pages or posts you want locked.

Privacy and cookies

The Utterances script talks to GitHub. If you run a cookie/consent banner, decide whether comment widgets load only after consent. This site also ships a cookie notice partial; keep the policy text honest about third-party embeds.

Verify

  1. Open a post with comments enabled.
  2. Sign in via the Utterances UI and post a test comment.
  3. In the GitHub repo, confirm an issue appears with label utteranc and a title/body tied to the page URL.
  4. Open a post with disable_comments: true and confirm the script is absent from the HTML.
curl -s https://devopstales.github.io/hugo/hugo-comments-github-issues/ \
  | grep -E 'utteranc.es|comments'

Summary

Install Utterances on your Pages (or docs) repo, drop a small script partial into Hugo, wrap it with disable_comments, and you get issue-backed discussions without a separate comment database. Static site, GitHub as the backend, one label to filter the noise in the issue tracker.