Changing Post Paths with Giscus Comments

Want to Change Your Hugo Post’s Path?

But don’t want to break Giscus comments wired up to the pathname? Here’s how to optionally bind your post’s comments using the discussionNumber (GitHub Discussion numeric ID) in your post’s frontmatter, letting you choose any slug you want, while allowing other existing posts to continue using pathname to bind comments.

Giscus integration with Hugo is well-documented elsewhere and is beyond the scope of this post. Integration differs based on the theme, but it’s not all that tricky. giscus.app is a huge help.

Follow these steps to use discussionNumber and path

These steps require Giscus to be part of your Hugo site already. A search for giscus.app in your code should help you find the script.

Update the script generation to detect discussionNumber

• For your Giscus script, detect whether the page’s frontmatter has discussionNumber.
• If it does, change the script output to use:

data-mapping="number"
data-term="DISCUSSION_NUMBER_VALUE"

For example, here is my /partials/layouts/comments.html which handles the Giscus posts UI.

{{/*
  Giscus comment integration with hybrid mapping support.
  Default: comments enabled unless front matter sets comments: false.

  Mapping strategy:
  - Standard: pathname mapping (site default, requires slug immutability)
  - Manual override: discussionNumber in front matter uses number mapping (for slug changes)
*/}}
{{ $disabled := eq .Params.comments false }}
{{ $giscus := site.Params.giscus }}
{{ if and (not $disabled) ($giscus.enable) }}
  <div id="comments" class="comments">
    {{- if .Params.discussionNumber -}}
      {{/* Manual override: use specific GitHub Discussion number (stable across any slug/title change) */}}
      <script src="https://giscus.app/client.js"
              data-repo="{{ $giscus.repo }}"
              data-repo-id="{{ $giscus.repoId }}"
              data-category="{{ $giscus.category }}"
              data-category-id="{{ $giscus.categoryId }}"
              data-mapping="number"
              data-term="{{ .Params.discussionNumber }}"
              data-strict="0"
              data-reactions-enabled="{{ if $giscus.reactionsEnabled }}1{{ else }}0{{ end }}"
              data-emit-metadata="{{ if $giscus.emitMetadata }}1{{ else }}0{{ end }}"
              data-input-position="{{ $giscus.inputPosition }}"
              data-theme="{{ $giscus.theme }}"
              data-lang="{{ $giscus.lang }}"
              crossorigin="anonymous"
              async>
      </script>
    {{- else -}}
      {{/* Default: use site-configured mapping (typically pathname) */}}
      <script src="https://giscus.app/client.js"
              data-repo="{{ $giscus.repo }}"
              data-repo-id="{{ $giscus.repoId }}"
              data-category="{{ $giscus.category }}"
              data-category-id="{{ $giscus.categoryId }}"
              data-mapping="{{ $giscus.mapping }}"
              data-strict="0"
              data-reactions-enabled="{{ if $giscus.reactionsEnabled }}1{{ else }}0{{ end }}"
              data-emit-metadata="{{ if $giscus.emitMetadata }}1{{ else }}0{{ end }}"
              data-input-position="{{ $giscus.inputPosition }}"
              data-theme="{{ $giscus.theme }}"
              data-lang="{{ $giscus.lang }}"
              crossorigin="anonymous"
              async>
      </script>
    {{- end -}}
    <noscript>Please enable JavaScript to view comments.</noscript>
  </div>
{{ else if not $disabled }}
  {{/* Giscus not yet configured; show placeholder to owner only (not rendered publicly unless you remove comment) */}}
  <!-- Comments would appear here once params.giscus.enable=true and configuration values set. -->
{{ end }}

Update the page’s frontmatter

Here is an earlier version of this page’s frontmatter:

---
title: "Comments Play Pen"
date: 2025-11-21
draft: false
discussionNumber: 1
---

Also Good for Migration

If you ever want to use a different domain or otherwise change the path to one or all of your posts, just add the discussionNumber to each post’s frontmatter.

Why Use discussionNumber Mapping?

• Multi-domain flexibility: If you serve the same blog from different domains or subdomains, discussionNumber mapping ensures all variants point to the same GitHub Discussion thread regardless of URL structure.
• Immutability: Once set, the discussionNumber never changes—even if you reorganize your entire site structure, rename categories, or change hosting providers.
• Canonical redirects: When implementing 301 redirects or Hugo aliases, discussionNumber mapping prevents comment fragmentation across old and new paths.

Automation

It is possible to programmatically generate this frontmatter. Here are some options:

1. PowerShell script run locally to get the discussionNumber (GitHub Discussion numeric ID) and if it exists for the post, update the post’s frontmatter
2. Ask AI to do it if available. GitHub Copilot offered to write the PS script. Maybe later.
3. GitHub Action on new discussion in the GitHub repo:
   • Trigger an action to look at the incoming discussion
   • Infer the correct post in the appropriate repo
   • Inject the appropriate frontmatter into the post
   • Generate a PR with the updated frontmatter

Finding the discussionNumber: You can obtain the numeric ID from the GitHub Discussions URL. For example, in https://github.com/owner/repo/discussions/42, the discussionNumber is 42 (the last segment of the URL).

Try It Out!

Want to see Giscus in action? Scroll down and try the comments below:

• Quick reaction: Just log in with your GitHub account and click the ❤️ if you found this post helpful.
• Test markdown: Comments support full markdown formatting. Try copying this into a comment to experiment with lists, headings, and italics—or create your own:

### Here is my heading
1. Super cool.
1. Give me more.
1. *more of that techy content*

• No GitHub account? They’re free! Just click “Sign in to GitHub” below, follow the prompts to create your account, and you can comment here and on many other sites across the web.