Comments

The comments module embeds a Giscus widget on your blog posts and docs pages, backed by GitHub Discussions. Each page gets its own discussion thread. Readers can comment without leaving your site.

Prerequisites

• A public GitHub repository with Discussions enabled (Settings → Features → Discussions).
• Your repo listed on giscus.app — the app generates the config values you need.

Get your Giscus values

1. Go to giscus.app.
2. Enter your repository name (e.g. owner/repo).
3. Choose a discussion category (General works for most sites).
4. Copy the generated values: data-repo-id and data-category-id.

You will need repo, repoId, category, and categoryId in your config.

Add the module

// karaoke.config.ts
import { defineConfig } from '@karaoke-cms/astro';
import { blog } from '@karaoke-cms/module-blog';
import { docs } from '@karaoke-cms/module-docs';
import { comments } from '@karaoke-cms/module-comments';

export default defineConfig({
  modules: [
    blog({ mount: '/blog', comments: true }),
    docs({ mount: '/docs', comments: false }),
    comments({
      repo: "owner/repo",
      repoId: "R_...",
      category: "General",
      categoryId: "DIC_...",
    }),
  ],
});

The comments() module must be present in modules[] alongside blog() and docs() — it provides the Giscus config. Without it, no widget is rendered even if comments: true is set on a module.

Config options

Option	Type	Required	Default	Description
repo	string	Yes	—	GitHub repo in owner/repo format
repoId	string	Yes	—	Repo node ID from giscus.app
category	string	No	"General"	Discussion category name
categoryId	string	Yes	—	Category node ID from giscus.app
enabled	boolean	No	true	Set to false to disable the module entirely

Per-module defaults

Control whether comments appear on an entire module by setting comments on blog() or docs():

blog({ mount: '/blog', comments: true })   // all blog posts show comments
docs({ mount: '/docs', comments: false })  // all docs pages hide comments

The default for both modules is false — you must opt in.

Per-page override

Override the module default for a single page using frontmatter:

---
title: "My Post"
publish: true
comments: false   # hides comments on this page only
---

---
title: "API Reference"
publish: true
comments: true    # shows comments on this page even if docs() has comments: false
---

The frontmatter value takes precedence over the module default.