中文 English

Gitalk Broken After Migration from Gridea to Hugo: Complete Troubleshooting and Fix Log

Published: 2026-03-01
gitalk gridea hugo github comment-system migration blog

Background

After migrating the blog entirely from Gridea to Hugo, pages load normally, but the comment section Gitalk appears to be malfunctioning:

  1. No obvious errors are reported on the page, but the comment section doesn’t load or display historical comments.
  2. Historical articles are not associated with their original issues.

This article documents a complete troubleshooting and fix process for future reference when migrating similar sites.

1. First, Confirm the Old Site’s Gitalk “Actual Behavior”

The old site (Gridea Notes theme) has the following Gitalk core logic:

id: (location.pathname).substring(0, 49)

That is: Directly use the URL path (up to 49 characters) as the unique identifier for Gitalk issues.

This step is crucial because if the new site changes the id algorithm, historical comment issues will “mismatch”.

2. Compare Hugo’s Implementation After Migration

After migration, two key differences were found in the Hugo templates:

  1. admin is rendered as a string instead of an array.
  2. id uses sha1(RelPermalink), which differs from the old site’s rules.

The actual snippet captured online (before fix) looks roughly like:

admin: "[\"margrop\"]",
id: "61a893da1bbe4c35fe4f8120cfc1f5c28f826ada"

This creates two problems:

  1. Type error in admin, causing Gitalk initialization to fail or behave unstably.
  2. id incompatible with old rules, historical comments cannot be mapped.

3. Fix Solution

Fix goal: Prioritize compatibility with old site behavior, restore all historical comments first.

1) Fix admin Rendering Type

In Hugo templates, change to output a genuine JavaScript array:

admin: {{ .admin | jsonify | safeJS }},

2) Restore Old Site id Rules

Revert from sha1 back to the old site’s path truncation rules:

{{ if gt (len $.RelPermalink) 49 }}
id: '{{ substr $.RelPermalink 0 49 }}',
{{ else }}
id: '{{ $.RelPermalink }}',
{{ end }}

3) Optimize Frontend Resource Availability (Domestic Networks)

Switch Gitalk static resources from unpkg to jsdelivr:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk/dist/gitalk.css">
<script src="https://cdn.jsdelivr.net/npm/gitalk/dist/gitalk.min.js"></script>

This step is not strictly required for Gitalk logic, but it can significantly reduce loading failure probability in certain network environments.

4. Verification Steps

1) Local Build Check

hugo --cleanDestinationDir

Confirm the generated page’s Gitalk snippet has changed to:

admin: ["margrop"],
id: "/en/post/hello-world/"

2) Post-Launch Source Code Review

curl -sL https://blog.margrop.net/en/post/hello-world/ | rg -n "gitalk|admin:|id:"

Confirm the live version is from the new template, not old cached content.

3) GitHub API Verify Historical Issue Mapping

For example, verify Hello World:

curl -sG "https://api.github.com/repos/margrop/margropcomment.margrop.io/issues" \
  --data-urlencode "state=all" \
  --data-urlencode "labels=Gitalk,/en/post/hello-world/"

If the corresponding issue can be found, historical comment mapping has been successfully restored.

5. Release Process (This Execution)

git add themes/simple/layouts/partials/gitalk.html
git commit -m "fix: restore gitalk compatibility and correct admin config"
git push origin master

bash scripts/deploy_github_pages.sh

This fix commit:

cae7cbe fix: restore gitalk compatibility and correct admin config

6. Conclusions and Lessons Learned

The root cause of this issue is not “Gitalk configuration lost”, but post-migration behavioral inconsistency:

  1. id generation rules changed, causing historical comment mapping to fail.
  2. Template rendering type error, causing admin to not be an array.

When migrating comment systems, the recommended priority order is:

  1. First, lock the old site’s id rules and keep them consistent.
  2. Verify the JavaScript type rendered by templates is correct (don’t just look at template source code).
  3. Use both online source code and GitHub API for dual verification to avoid “appears normal” but actually unassociated.

References