Giscus Comments
Add a GitHub Discussions-powered comment system to your documentation pages.
Giscus is a comment widget powered by the GitHub Discussions API. Visitors can leave comments using their GitHub account without any external database or moderation overhead.
Finding Your Repository ID
Giscus requires both the repository name and its internal GraphQL ID from GitHub (repoId). You can find the repoId using the GitHub API:
# Replace 'owner' and 'repo' with your repository coordinates
curl -H "Authorization: Bearer YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/owner/repo \
| grep '"id"' | head -1
Or use the Giscus Configuration Tool — it generates the complete configuration after you enter your repository URL.
Configuration Reference
| Property | Type | Required | Description |
|---|---|---|---|
repo | string | ✓ | GitHub repository in owner/repo format. |
repoId | string | ✓ | Internal GraphQL ID of the GitHub repository. |
category | string | — | Discussion category where comments are stored (e.g. 'General'). |
categoryId | string | — | Discussion category ID (required if category is set). |
mapping | string | — | How to map pages to discussions. One of 'pathname', 'url', 'title', 'og:title', 'specific', 'number'. Defaults to 'pathname'. |
strict | boolean | '0' | '1' | — | Only allow comments on pages with a matching discussion. |
reactionsEnabled | boolean | '0' | '1' | — | Enable or disable reaction emojis on comments. |
emitMetadata | boolean | '0' | '1' | — | Emit discussion metadata as events. |
inputPosition | 'top' | 'bottom' | — | Position of the comment input box. Defaults to 'top'. |
theme | string | — | Giscus theme name (e.g. 'light', 'dark'). Defaults to 'light'. |
darkTheme | string | — | Giscus theme name for dark mode (e.g. 'dark_dimmed'). Defaults to the value of theme. |
lang | string | — | Language code for the Giscus UI (e.g. 'en', 'es'). |
loading | 'lazy' | 'eager' | — | Loading strategy for the Giscus iframe. Defaults to 'lazy'. |
Complete Configuration
integrations: {
feedback: {
giscus: {
repo: 'your-org/your-repo',
repoId: 'R_kgDOXXXXXXXX',
category: 'General',
categoryId: 'DIC_kwDOXXXXXXXX',
mapping: 'pathname',
strict: '1',
reactionsEnabled: '1',
emitMetadata: '0',
inputPosition: 'bottom',
theme: 'light',
darkTheme: 'dark_dimmed',
lang: 'en',
loading: 'lazy',
},
},
}
Dark Mode Support
When the user switches between light and dark themes, the Giscus iframe automatically updates its theme via postMessage. If you specify a different darkTheme, Giscus will use the appropriate theme based on the site's current mode.
integrations: {
feedback: {
giscus: {
repo: 'your-org/your-repo',
repoId: 'R_kgDOXXXXXXXX',
theme: 'light',
darkTheme: 'dark_dimmed',
},
},
}
Using the Component Directly
If you're using a custom layout and want full control over where Giscus appears, import the <Giscus> component:
import { Giscus } from 'boltdocs/client'
export function MyLayout({ children }) {
return (
<div>
{children}
<Giscus />
</div>
)
}
The <Giscus /> component reads all the configuration from integrations.feedback.giscus automatically and handles theme syncing.
Troubleshooting
Comments don't load
- Verify that
repoandrepoIdare correct - Make sure the Giscus App on GitHub is installed on the repository
- Check the browser console for CSP or CORS errors
Incorrect discussion mapping
If comments from one page appear on another, review your mapping config. 'pathname' (default) maps each page's URL to a unique discussion.
Theme mismatch
If the Giscus widget doesn't match your site's theme, verify that the theme and darkTheme values are valid Giscus theme names. Common values: 'light', 'dark', 'dark_dimmed', 'transparent_dark', 'preferred_color_scheme'.
