Fixing Up Broken Giscus Discussion Links

  • 3 Min To Read
  • 05 Oct, 2023


I am using Giscus to drive comments on my site, you can read about how to set it up here . Giscus has some functionality you can turn on called strict matching, which ensures the correct post is mapped to the correct discussion (whereas by default it uses fuzzy matching). If you change the URL of your blog post…guess what? The link to the respective discussion on Github will be lost. Easiest way to resolve this…don’t rename your posts. But if you really need to then here’s how to fix them up.

How does Giscus map a discussion to a post?

Here’s an example discussion, if I edit the discussion in Github, it exposes a comment block that is hidden…

# post/2023/automator-convert-image-to-webp-quick-action/

How to use MacOS automator to automatically convert images directly from finder

<!-- sha1: 94472042770b00ae48da784595797faaafc0d654 -->

Note, this is the discussion I broke, I will fix it up later in the post.

The heading of the discussion has the post path, but it is also the title of the discussion. The discussion body also has a URL that generated the discussion. What specifically creates the link is the hash in the comment block. The has is a SHA-1 hash of the post path, which in turn is the title of the discussion by default.

The problem

I recently swapped themes and didn’t realise that my posts were being presented under the “post” path whereas historically they were just under the root of the site. Before fixing it, someone commmented on one of my posts and now I have fixed the URLs, the link to the discussion is broken because the hash isn’t correct for the current path of the post. For a short period of time this was the URL of the post in question;

But once fixed, the URL was;

And now I have no comments…

screenshot shows the footer of the post in question where the comments are empty

How to fix it up

The example discussion above is the discussion I need to fix. The title reads post/2023/automator-convert-image-to-webp-quick-action/ therefore, the SHA-1 in the comment block (94472042770b00ae48da784595797faaafc0d654) is based on this string. To fix up my discussion I only need to update the hash but for completeness I’ll update the heading and the title. The has needs to be of the following string 2023/automator-convert-image-to-webp-quick-action/ (note that it includes a trailing backspace) which is sha1: 8988346ac515dd12f757612795587de33aa191ca. You can generate this hash various ways, I just did it using MD5 hash generator .

The fixed discussion will look like this;

# 2023/automator-convert-image-to-webp-quick-action/

How to use MacOS automator to automatically convert images directly from finder

<!-- sha1: 8988346ac515dd12f757612795587de33aa191ca -->

Note here, I have updated the header in the discussion, and I’ve also updated the title. Neither is necessary but it just looks tidier. You change the title by clicking the edit button to the right of the title, whereas the discussion block is amended by selecting the ellipses next to the discussion block.

screenshot shows the github discussion, there is an edit button to the right of the title that allows you to edit the title, the discussion block has an ellipses button next to it which allows you to edit the discussion

And now I have comments again!

screenshot shows the footer of the post in question with the restored comments!


Moral of the story, don’t change your URLs :) but if for whatever reason you need to, you can fix up your Giscus discussions by updating the title and the hash! You can read about how the strict matching works here .