add user feedback to jekyll docs with giscus

Why Feedback Systems Matter in Documentation

Even the most well-maintained documentation will eventually miss edge cases, misunderstandings, or outdated references. Allowing users to provide feedback ensures your documentation evolves to meet real needs. But in static site setups like Jekyll on GitHub Pages, traditional comment systems are either bloated or unavailable. Fortunately, modern tools like Giscus and GitHub Discussions offer a solution that fits seamlessly into static workflows.

Choosing the Right Feedback Mechanism

Issues With Traditional Comment Systems

• Disqus requires external scripts and ads unless you pay for it.
• Staticman requires a backend service and is difficult to maintain.
• Form services like Google Forms feel disjointed from the documentation UX.

Benefits of Giscus

• Uses GitHub Discussions behind the scenes.
• Stores comments directly in your repository’s discussion board.
• No backend required – just a GitHub account and a public repo.
• Lightweight and privacy-respecting.

How Giscus Works

Giscus is an open-source commenting system that leverages GitHub Discussions for storing user comments. It maps a discussion to each page on your site by using metadata like URL, pathname, or title. When users comment, their messages are stored in GitHub – meaning your community’s input is version-controlled and searchable.

Prerequisites

• A GitHub repository with Discussions enabled.
• Public visibility (private repos are not supported by Giscus).
• Owner or admin access to configure Giscus.

Setting Up GitHub Discussions

Enable Discussions in Your Repository

Go to your repository settings, scroll to the “Features” section, and check the box for “Discussions.” Create at least one category (e.g., "Docs Feedback") to get started.

Understanding Discussion Categories

Giscus needs at least one category to use as the root for comments. You can choose to route all page feedback into a single category or create one per section of your site for better organization.

Installing Giscus in Jekyll

Embed the Giscus Script

In your Jekyll layout (e.g., _layouts/default.html or _includes/comments.html), add the following snippet where you want the comment box to appear:

<script src="https://giscus.app/client.js"
        data-repo="yourusername/yourrepo"
        data-repo-id="REPO_ID"
        data-category="Docs Feedback"
        data-category-id="CATEGORY_ID"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="light"
        crossorigin="anonymous"
        async></script>
<noscript>Please enable JavaScript to view the comments.</noscript>

How to Find the Repo ID and Category ID

Use the Giscus configuration tool at giscus.app to generate the appropriate values. This tool uses OAuth with your GitHub account to retrieve IDs for your repository and discussion categories automatically.

Optional: Use a Dedicated Include File

Create a reusable include like _includes/giscus.html and add:

{% raw %}
<div id="comments">
  <script src="https://giscus.app/client.js"
    data-repo="yourusername/yourrepo"
    data-repo-id="REPO_ID"
    data-category="Docs Feedback"
    data-category-id="CATEGORY_ID"
    data-mapping="pathname"
    data-theme="light"
    crossorigin="anonymous"
    async></script>
  <noscript>Enable JavaScript to view comments.</noscript>
</div>
{% endraw %}

Then add {% raw %}{% include giscus.html %}{% endraw %} at the bottom of your documentation layout or specific pages.

Customizing the Feedback Experience

Mapping Options

Choose how Giscus maps a page to a GitHub Discussion:

• pathname – Uses the path part of the URL (recommended for Jekyll).
• url – Maps exactly by the full URL.
• title – Uses the page’s title metadata.

Dark Mode & Themes

You can dynamically switch the Giscus theme by listening for dark mode changes. Set data-theme="preferred_color_scheme" or switch manually using JavaScript when toggling themes on your site.

Moderation and Community Management

Since Giscus leverages GitHub Discussions, moderation is straightforward. As a repository admin, you can:

• Pin important comments
• Move or merge discussions
• Report or delete inappropriate feedback

Encouraging Participation

Place a call-to-action above your comment section such as:

“Have feedback or found something unclear? Let us know below – we’re always improving our documentation.”

This kind of prompt gently nudges users to engage and contribute.

Tracking Engagement and Feedback Trends

Reviewing Discussions

Visit the “Discussions” tab on your GitHub repo to see which pages get the most interaction. This helps you prioritize documentation improvements based on actual user engagement.

Analytics Integration

While Giscus doesn’t track metrics itself, you can combine it with tools like Plausible or Cloudflare Web Analytics to measure visits to your comment-enabled pages.

Scaling Up: Comments Per Section or Page Type

For large documentation projects, consider changing the feedback strategy by section. For example:

• Tutorial pages – Allow open discussion per page
• API references – Disable comments or link to centralized thread
• Changelog or roadmap – Pin feedback to a master thread

Using Multiple Giscus Categories

Assign different discussion categories for different site areas (e.g., Tutorials, FAQ, Guides) to keep conversations organized and relevant.

Conclusion and What’s Next

Integrating a user feedback loop into your Jekyll site with Giscus bridges the gap between static content and dynamic interaction. Without compromising speed or simplicity, you empower your users to become contributors to better documentation. It’s lightweight, version-controlled, and ties seamlessly into the GitHub ecosystem.

In the next article, we’ll explore how to generate dynamic site-wide search with zero backend using Lunr.js and client-side indexing, tailored for Jekyll documentation hosted on GitHub Pages.