Migrating comments to giscus

Table of Contents

Updated in 2026-11.

Followed this guide: https://www.patrickthurmond.com/blog/2023/12/11/commenting-is-available-now-thanks-to-giscus

Add the following to layout/_partial/article.ejs

<% if (!index && post.comments) { %>
<section class="giscus"></section>
<script src="https://giscus.app/client.js"
 data-repo="MaskRay/maskray.me"
 data-repo-id="FILL IT UP"
 data-category="Blog Post Comments"
 data-category-id="FILL IT UP"
 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"
 data-loading="lazy"
 crossorigin="anonymous"
 async>
</script>
<% } %>

At first, comments from Disqus were not migrated. While you can create Github Discussions via GraphQL API, I didn't find a solution that works out of the box. https://www.davidangulo.xyz/posts/dirty-ruby-script-to-migrate-comments-from-disqus-to-giscus/ provides a Ruby solution, which is promising but no longer works.

Failed to define value method for :name, because EnterpriseOrderField already responds to that method. Use `value_method:` to override the method name or `value_method: false` to disable Enum value me
thod generation.
Failed to define value method for :name, because EnvironmentOrderField already responds to that method. Use `value_method:` to override the method name or `value_method: false` to disable Enum value m
ethod generation.
Failed to define value method for :name, because LabelOrderField already responds to that method. Use `value_method:` to override the method name or `value_method: false` to disable Enum value method
generation.
...
.local/share/gem/ruby/3.3.0/gems/graphql-client-0.25.0/lib/graphql/client.rb:338:in `query': wrong number of arguments (given 2, expected 1) (ArgumentError)
        from g.rb:42:in `create_discussion'

Importing Disqus comments

In 2026-11 I imported the comments from the Disqus export (comments.xml) with a Python script that calls the GitHub GraphQL API via gh api graphql. The export has 589 comments from 2011 to 2025, excluding deleted and spam ones. 577 of them went into 135 discussions; the rest belong to pages that no longer exist or have no comment box. If you've left comments in the past, thank you, and they are back.

Some notes:

  • A Disqus thread records the URL at the time of the first comment: /2011/07/12/blogging-with-makefile.html, maskray.tk/..., or /blog/2020-11-26-all-about-symbol-versioning, which is now /blog/all-about-symbol-versioning. Each needs to be mapped to the current pathname.
  • A discussion created by giscus has the title blog/<path> and a body ending with <!-- sha1: ... -->, the SHA-1 of the title. Creating discussions in the same shape lets giscus find them.
  • GitHub Discussions nest only one level, so a reply to a reply is attached to its top-level comment.
  • The comments are posted from my account, each prefixed with the original author and date.
  • @name in an old comment would notify the GitHub user with the same name, so such text is wrapped in <code>. Links to GitHub issues are turned into code text as well, so that they don't add cross-references to those issues.
  • After about 50 discussions and 250 comments at one mutation every 8 seconds, createDiscussion started to fail with "was submitted too quickly". After an hour's pause, one mutation every 15 seconds worked.

giscus finds the discussion for a page via GitHub search: in:title "blog/<path>" with data-strict="0", or in:body "<sha1>" with data-strict="1". Non-strict matching is a phrase search, so blog/glibc can pick up blog/glibc-and-dt-gnu-hash. I have switched to data-strict="1".

Shortening some URLs (dropping the date) had orphaned their discussions, whose titles still used the old pathnames. In addition, GitHub search returned only 1 of the 24 existing discussions, so most pages showed an empty comment box. Retitling the discussions to the current pathnames (and updating the SHA-1) made them searchable again.