Integrating Gitalk Comment System into a Docsify Documentation Site
This article explains how to add a Gitalk-based comment feature to a Docsify‑generated documentation site, covering Gitalk fundamentals, GitHub OAuth app setup, integration steps, custom JavaScript tweaks for URL handling, common pitfalls, and a detailed appendix of configuration parameters.
Background: The author’s open‑source project PassJava has an online technical documentation site built with Docsify but lacks a comment feature, so they decided to add one using Gitalk.
Gitalk introduction: Gitalk is a comment plugin based on GitHub Issues and Preact, supporting GitHub login, multiple languages, personal or organization repos, distraction‑free mode, and shortcut‑key submission.
Principle: Gitalk creates a GitHub Issue for each page and stores comments as Issue comments. The page’s unique identifier (id) and title are derived from the repository name and label.
Adding comments: The author shows the API endpoint for creating comments and the request payload.
GitHub OAuth configuration: Steps to create a GitHub OAuth application (Settings → Developer settings → OAuth Apps → New OAuth App) and obtain client ID and secret.
Integrating Gitalk: Include the CSS and JS files, add a <div id="gitalk-container"></div> placeholder, and instantiate Gitalk with required options (clientID, clientSecret, repo, owner, admin, id, title).
Customizations: (1) Decode URL‑encoded titles with decodeURI(title) . (2) Extract the title after the hash part of the URL. (3) Truncate id and title to 50 characters. (4) Listen to window.onhashchange to reload the page when navigating between Docsify pages.
Pitfalls encountered: receiving email notifications, missing issues due to JavaScript errors, HTTP 401/422 errors caused by using a GitHub App instead of an OAuth App or id length limits, and all pages showing the same comments if id is not unique.
Appendix: Lists the main Gitalk parameters (clientID, clientSecret, repo, owner, admin, id, title, number, labels, body, language, perPage, distractionFreeMode, pagerDirection, createIssueManually, proxy, flipMoveOptions, enableHotKey) with brief descriptions.
References: Links to a SegmentFault article and the Gitalk GitHub repository.
Wukong Talks Architecture
Explaining distributed systems and architecture through stories. Author of the "JVM Performance Tuning in Practice" column, open-source author of "Spring Cloud in Practice PassJava", and independently developed a PMP practice quiz mini-program.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.