Adding Comments Without Giving Up or Using Disqus

Two Things Before Comments

Before wiring up Giscus, two unrelated improvements happened in the same session.

Organizing Posts by Year

All posts were living flat in content/posts/. Fine at ten posts. Annoying at fifty. Hugo's URL structure is driven by the date frontmatter, not the folder path, so moving files into year subdirectories doesn't change any URLs.

content/posts/
  2026/
    ethics-autonomous-vehicles.md
    jira-as-a-signal.md
    ...

The hugo.toml permalink config handles the URL:

[permalinks]
  posts = "/:year/:month/:filename/"

Hugo reads :year and :month from each post's date field, not from where the file sits. Moving ethics-autonomous-vehicles.md into 2026/ doesn't change its URL at /2026/05/ethics-autonomous-vehicles/.

Side effect: Hugo generates a list page at /posts/2026/. It's not linked anywhere - it exists as a hidden artifact.

Any aliases in post frontmatter move with the files and keep working.

mkdir -p content/posts/2026
mv content/posts/*.md content/posts/2026/

Run hugo to verify - if it builds clean, the URLs are intact.

Setting Up Giscus

1. GitHub Account and Repo

Giscus needs a public GitHub repo with Discussions enabled. Create a dedicated repo so comments don't live next to your code.

The repo should be under the same identity you want associated with the site. A dedicated GitHub account - or a username that matches your site's brand - keeps your personal account out of the visible repo ownership.

Create the repo:

# Authenticated as your site account
gh repo create YOUR_ORG/YOUR_REPO_NAME --public --description "Giscus comments"

In the repo settings, enable Discussions: Settings → Features → Discussions.

Disable what you don't need: Wikis, Issues, Projects. This repo's only job is holding Discussion threads.

2. Discussion Category

In the repo's Discussions tab, the default General category works. The recommended setup is to use an Announcements type category instead - this means only you (the repo owner) can create new discussion threads directly on GitHub. Readers can still comment; they just can't open new threads manually. Giscus creates threads automatically on first page load, so the restriction doesn't affect normal usage.

Create an Announcements category if one doesn't exist, or set an existing category's type to Announcements in the category settings.

3. Install the Giscus GitHub App

Go to github.com/apps/giscus and install it on your account. When prompted, scope it to the comments repo only - not all repos.

4. Get the Config Snippet

Go to giscus.app. Fill in:

• Repository: YOUR_ORG/YOUR_REPO_NAME
• Discussion category: the Announcements category you created

The page will populate data-repo-id and data-category-id automatically. Copy the generated <script> block at the bottom.

5. Add to Hugo

In themes/YOUR_THEME/layouts/_default/single.html, add the Giscus script after the post content, wrapped in a section check so it only appears on posts:

{{ if eq .Section "posts" }}
<div class="giscus-comments">
  <script src="https://giscus.app/client.js"
          data-repo="YOUR_ORG/YOUR_REPO_NAME"
          data-repo-id="YOUR_REPO_ID"
          data-category="Announcements"
          data-category-id="YOUR_CATEGORY_ID"
          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>
</div>
{{ end }}

data-mapping="pathname" ties each Discussion thread to the post's URL path. data-theme="transparent_dark" lets the widget inherit your page background instead of rendering its own.

The {{ if eq .Section "posts" }} guard means the widget won't appear on pages like About or Contact that use the same single.html template.

The widget sits inside a styled container with a floating [ external transmissions ] label - amber, same treatment as the voice blocks. CSS is straightforward: .giscus-comments gets the border and glow, .giscus-comments-label gets positioned absolute at the top edge. Amber on near-black is 13.5:1 contrast, clears WCAG AAA.

One thing that bit us on this site: Hugo's template lookup prefers layouts/_default/single.html at the project root over the same file inside themes/. This site had both. The script went into the theme file first, built clean, and didn't appear anywhere. Took a grep of the built HTML to catch it. If Giscus isn't showing up after a rebuild, that's the first place to check.

Adding a Newsletter Subscribe Form

Buttondown handles the newsletter side. Create an account at buttondown.com, then use Buttondown's embed API to wire a subscribe form directly into the site - no JavaScript bundle, no third-party widget loader.

Create a partial at layouts/partials/subscribe.html:

<div class="subscribe-block">
  <div class="subscribe-label">// SUBSCRIBE //</div>
  <p class="subscribe-desc">New posts, weekly. No tracking. Unsubscribe anytime.</p>
  <form
    action="https://buttondown.com/api/emails/embed-subscribe/YOUR_USERNAME"
    method="post"
    class="subscribe-form"
  >
    <input type="email" name="email" id="bd-email" placeholder="your@email.com" required />
    <button type="submit">subscribe</button>
  </form>
</div>

Replace YOUR_USERNAME with your Buttondown username. Then include the partial in layouts/_default/single.html wherever you want the form to appear - after post content, before the Giscus widget.

{{ partial "subscribe.html" . }}

Buttondown's embed endpoint handles the form POST and returns a redirect. No AJAX, no API keys in the client, no cookies. The form works with JavaScript disabled.