How to fix broken Giscus discussion links
Table of Contents
A long time ago in a galaxy far, far away…
This post is over 12 months old and Hugo is evolving. Please be mindful of that when reading this post, young Padawan, as it could be outdated. I try to keep things up to date as much as possible. If you think something needs updating, please let me know in the comments.
Introduction
I am using Giscus to drive comments on my site, you can read about how to set it up in this blog post. 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 is how to fix them up.
How does Giscus map a discussion to a post?
Here is 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
https://www-justinjbird-me.translate.goog/post/2023/automator-convert-image-to-webp-quick-action/?_x_tr_sl=auto&_x_tr_tl=fr&_x_tr_hl=fr&_x_tr_pto=wapp
<!-- 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 commented 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;
https://www.justinjbird.me/post/2023/automator-convert-image-to-webp-quick-action
But once fixed, the URL was;
https://www.justinjbird.me/2023/automator-convert-image-to-webp-quick-action
And now I have no comments…
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 will 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
https://www-justinjbird-me.translate.goog/post/2023/automator-convert-image-to-webp-quick-action/?_x_tr_sl=auto&_x_tr_tl=fr&_x_tr_hl=fr&_x_tr_pto=wapp
<!-- sha1: 8988346ac515dd12f757612795587de33aa191ca -->
Note here, I have updated the header in the discussion, and I have 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.
And now I have comments again!
Summary
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 in this help section.
#mtfbwy