How to integrate Giscus comments into AstroPaper

Hosting a thin static blog on a platform like GitHub Pages has numerous advantages, but also takes away some interactivity. Fortunately, Giscus exists and offers a way to embed user comments on static sites.

Table of contents

How Giscus works

Giscus uses the GitHub API to read and store comments made by GitHub users in the Discussions associated with a repository.

Embed the Giscus client-side script bundle on your site, configure it with the correct repository URL, and users can view and write comments (when logged into GitHub).

The approach is serverless, as the comments are stored on GitHub and dynamically loaded from there on client side, hence perfect for a static blog, like AstroPaper.

Setting up Giscus

Giscus can be set up easily on giscus.app, but I will outline the process shortly still.

Prerequisites

Prerequisites to get Giscus working are

• the repository is public
• the Giscus app is installed
• the Discussions feature is turned on for your repository

If any of these conditions cannot be fulfilled for any reason, unfortunately Giscus won’t work. Consider alternatives such as Utterances.

Configuration

Navigate to giscus.app and follow the on-screen instructions to configure your Giscus instance. You’ll need to:

1. Enter your GitHub repository URL
2. Choose a mapping between the embedding page and the GitHub Discussion
3. Pick a category for discussions
4. Select your preferred features (reactions, metadata, etc.)
5. Choose a theme

After configuration, you’ll receive a <script> tag to embed in your site.

Adding Giscus to AstroPaper

Create a new component for Giscus comments:

<!-- src/components/Comments.astro -->
<section class="giscus mx-auto mt-10 w-full">
  <script
    src="https://giscus.app/client.js"
    data-repo="[YOUR-REPO]"
    data-repo-id="[YOUR-REPO-ID]"
    data-category="[YOUR-CATEGORY]"
    data-category-id="[YOUR-CATEGORY-ID]"
    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"
    crossorigin="anonymous"
    async
  ></script>
</section>

Then, add the component to your post layout:

<!-- src/layouts/PostDetails.astro -->
<Layout>
  <!-- post content -->
  <Comments />
</Layout>

Handling Dark Mode

Since AstroPaper supports light and dark themes, you’ll want Giscus to match. You can listen for theme changes and update the Giscus iframe accordingly:

function sendMessage(message: { setConfig: { theme: string } }) {
  const iframe = document.querySelector<HTMLIFrameElement>(
    "iframe.giscus-frame"
  );
  if (!iframe) return;
  iframe.contentWindow?.postMessage(
    { giscus: message },
    "https://giscus.app"
  );
}

// Listen for theme changes
document.addEventListener("theme-change", () => {
  const theme = document.documentElement.getAttribute("data-theme");
  sendMessage({
    setConfig: {
      theme: theme === "dark" ? "dark" : "light",
    },
  });
});

Conclusion

With Giscus, you can add a fully functional comment system to your AstroPaper blog without needing a backend server. Comments are stored in GitHub Discussions, making them easy to moderate and backed by GitHub’s infrastructure.