Tutorial: How to Add Comments to an Astro 4.0 Blog with Giscus 1.0 and GitHub 2026

Static site generators like Astro 4.0 offer blazing fast performance, but adding dynamic features like comments traditionally requires third-party services. Giscus 1.0, a lightweight comment system powered by GitHub Discussions, eliminates the need for external databases when paired with GitHub 2026’s updated OAuth and Discussions APIs. This tutorial walks you through every step to integrate Giscus comments into your Astro 4.0 blog.

Prerequisites

• An existing Astro 4.0 blog project (initialized with npm create astro@4 or similar)
• A GitHub 2026 account with a public repository for your blog content
• Node.js 20+ installed locally
• Basic familiarity with Astro components and Markdown frontmatter

Step 1: Configure GitHub 2026 for Giscus

First, you’ll need to set up GitHub Discussions and a GitHub OAuth App to authorize Giscus to read/write to your repository’s discussions.

Enable GitHub Discussions

Navigate to your blog’s GitHub repository, go to Settings > General, scroll to the Features section, and check the box for Discussions. Click Set up discussions to create a default category (we’ll configure this later for Giscus).

Create a GitHub OAuth App

Go to Settings > Developer settings > OAuth Apps in your GitHub account, click New OAuth App, and fill in the following:

• Application name: Giscus - [Your Blog Name]
• Homepage URL: Your blog’s production URL (e.g., https://yourblog.com)
• Authorization callback URL: https://giscus.app

Once created, copy the Client ID and generate a Client Secret — you’ll need these later.

Step 2: Set Up Giscus 1.0

Navigate to giscus.app and fill in the configuration form:

1. Enter your GitHub repository name (e.g., username/blog-repo)
2. Select the Discussions category you created earlier (or create a new one named "Comments")
3. Choose your preferred Giscus 1.0 features: theme (match your blog’s dark/light mode), language, and comment sorting
4. Enter the OAuth App Client ID and Client Secret you copied earlier

Giscus will generate a unique data-repo, data-repo-id, data-category, data-category-id, data-mapping, and data-reactions-enabled values. Copy all of these — they’ll be used in your Astro component.

Step 3: Create a Giscus Component in Astro 4.0

Create a new file at src/components/Giscus.astro in your Astro project. This component will load the Giscus script and render comments for individual blog posts.

---
// src/components/Giscus.astro
const {
  repo = "your-username/your-blog-repo",
  repoId = "YOUR_REPO_ID",
  category = "Comments",
  categoryId = "YOUR_CATEGORY_ID",
  mapping = "pathname",
  reactionsEnabled = "1",
  theme = "light",
} = Astro.props;
---






  // Handle theme switching if your blog supports dark/light mode
  const observer = new MutationObserver(() => {
    const giscusFrame = document.querySelector("iframe.giscus-frame");
    if (giscusFrame) {
      const currentTheme = document.documentElement.classList.contains("dark") ? "dark" : "light";
      giscusFrame.contentWindow.postMessage(
        { giscus: { setConfig: { theme: currentTheme } } },
        "https://giscus.app"
      );
    }
  });
  observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });

Replace the placeholder repo, repoId, categoryId values with the ones you copied from Giscus.app. The second script block handles automatic theme switching if your Astro blog uses a dark/light mode toggle.

Step 4: Add Giscus to Blog Post Layouts

Open your blog post layout file (usually src/layouts/BlogPost.astro or similar). Import the Giscus component and add it below your post content, before the closing or

tag of the layout.

---
// src/layouts/BlogPost.astro
import Giscus from "../components/Giscus.astro";
import BaseLayout from "./BaseLayout.astro";

const { frontmatter } = Astro.props;
---



    {frontmatter.title}

      Published: {frontmatter.pubDate}

This will render Giscus comments at the bottom of every blog post that uses the BlogPost layout.

Step 5: Test Your Integration

Start your Astro dev server with npm run dev, navigate to a blog post, and verify that the Giscus comment section loads correctly. Test submitting a comment (you’ll need to authorize with your GitHub account the first time), and check that the comment appears in your GitHub repository’s Discussions tab.

If comments don’t load, check the browser console for errors — common issues include incorrect repo IDs, missing OAuth App configuration, or ad blockers blocking the Giscus script.

Step 6: Deploy and Verify

Once tested locally, deploy your Astro 4.0 blog to your preferred hosting provider (Netlify, Vercel, GitHub Pages, etc.). Update your GitHub OAuth App’s Homepage URL and Authorization callback URL if your production URL differs from local. Verify that comments work in production, and check GitHub 2026’s Discussions tab to confirm new comments are syncing correctly.

Conclusion

Integrating Giscus 1.0 with Astro 4.0 and GitHub 2026 gives you a free, open-source comment system with no external dependencies beyond GitHub. You retain full ownership of your comment data, and GitHub’s 2026 API updates ensure long-term compatibility and improved performance. Customize the Giscus theme and settings to match your blog’s branding, and enjoy engaging with your readers directly through GitHub Discussions.