# Add Giscus Comments to a Docusaurus Blog

Yes. An agent adds giscus comments under each Docusaurus blog post with a swizzled BlogPostItem, matched to your color mode and locale, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-giscus-comments/docusaurus/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the blog is built before it touches a theme component, because a swizzle that fights the site's own customizations is the usual way this goes wrong. In a site laid out like electron/website, `docusaurus.config.ts` pins `@docusaurus/core` and `@docusaurus/preset-classic` at 3.10.0, runs the blog plugin from `blog/` with `blogSidebarCount: 'ALL'`, `onInlineAuthors: 'ignore'` and `onUntruncatedBlogPosts: 'ignore'`, declares eight locales with `en` as the default and a `localeConfigs` block that sets each translated `baseUrl` by hand, and turns on `respectPrefersColorScheme` under `colorMode`. The `blog/` directory holds 134 posts with `authors` keys resolved from `blog/authors.yml`, and `src/theme/README.md` lists what is already swizzled: `DocSidebarItem`, `TOC`, a `Footer` and a `BlogPostItem/Footer/ReadMoreLink` that wraps the read-more link in the site's own button class. There are no comments on any post, no giscus script and no `@giscus` package in `package.json`.

Then it reads the toolchain that will judge the change. `package.json` sets `packageManager` to Yarn 4.10.3, `engines.node` to 24 and `.nvmrc` to 24.22.1; `.yarnrc.yml` turns `enableScripts` off and sets `npmMinimalAgeGate` to 10080 minutes, so a package version younger than seven days cannot be added. The `lint` script runs `tsc --noEmit`, then `oxfmt --check`, `oxlint` over `docusaurus.config.ts`, `src` and `scripts`, and `markdownlint-cli2`, and `.github/workflows/pull-request.yml` runs exactly that after `yarn install --immutable`. `build` is `docusaurus build --locale en`; the translated locales build separately from `i18n/`, which is why the theme code must not assume one `baseUrl`.

The agent adds `@giscus/react` with `yarn add`, which respects the age gate, and writes `src/theme/BlogPostItem/index.tsx` as a wrapper: it renders the original `BlogPostItem` from `@theme-original/BlogPostItem`, then, only when `useBlogPost().isBlogPostPage` is true, a `Comments` component below it, so the list pages at `/blog` stay as they are. `src/components/GiscusComments.tsx` reads `repo`, `repoId`, `category` and `categoryId` from `themeConfig.giscus` in `docusaurus.config.ts` through `useThemeConfig`, maps `useColorMode().colorMode` to the giscus `light` and `dark` themes so the widget follows the toggle without a reload (the React component updates the embed through `postMessage` when a prop changes), and passes `useDocusaurusContext().i18n.currentLocale` as `lang`. It sets `mapping` to `specific` with `term` set to the post's `metadata.permalink` stripped of its locale prefix, so the English and the Japanese rendering of one post share one discussion instead of eight.

It wires `strict` to `1` so a discussion is matched by its hashed term, `reactionsEnabled` to `1`, `inputPosition` to `top` and `loading` to `lazy`, puts the new component through the same `clsx` and SCSS module conventions the other components in `src/components` use, and documents the one step it cannot do: installing the giscus GitHub App on the repository and turning on Discussions, which the pull request describes with the exact `repoId` and `categoryId` lookup from giscus's own configuration page. In its sandbox the agent runs `yarn install --immutable`, `yarn lint` and `yarn build`, then serves the build and loads one post in each color mode to confirm the iframe is requested with the expected `data-theme` and `data-term`.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add giscus comments to the blog posts of this Docusaurus site. Read package.json, .yarnrc.yml, .nvmrc, docusaurus.config.ts, src/theme/README.md, the existing files under src/theme/BlogPostItem, src/components and .github/workflows/pull-request.yml first. Add @giscus/react with yarn, swizzle BlogPostItem as a wrapper that renders the original item and then a comments component only on a single post page, never on the blog list. Read repo, repoId, category and categoryId from a giscus block under themeConfig in docusaurus.config.ts with placeholder values and a comment on how to fill them, follow the site's color mode for the giscus theme, pass the current locale as lang, and map discussions with mapping specific and a term that is the post permalink without its locale prefix so every translation of a post shares one discussion. Run yarn install --immutable, yarn lint and yarn build, and open a pull request that explains the giscus app install and Discussions setup the maintainers must do by hand. Do not change any post or any other swizzled component.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `src/theme/BlogPostItem/index.tsx`, `src/components/GiscusComments.tsx` with its SCSS module, a `giscus` block under `themeConfig` in `docusaurus.config.ts`, the `@giscus/react` line in `package.json` and the matching `yarn.lock` change, and a paragraph in `src/theme/README.md` listing the new swizzle and why it is a wrapper rather than an eject. The description pastes the `yarn lint` and `yarn build` output and the two screenshots of a post with the widget in light and dark mode.

What the maintainers do before merging: install the giscus app on the repository, enable Discussions, create or pick the category, and paste `repoId` and `categoryId` into the config block. A reviewer also decides whether comments belong on every post or only on ones with a `comments: true` front matter flag, which the component reads if present, and whether the `lazy` loading suits posts that end above the fold.

## Run it on every new blog post

Once the component is in, every new post under `blog/` gets comments with no further work, since the wrapper applies to every `BlogPostItem` on a single-post page. The run that is worth repeating is the check that a change to the theme did not break it: an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if the pull request touches src/theme or docusaurus.config.ts, build the site, open one blog post and confirm the giscus iframe is requested with the post's term, then comment with the result" starts one run per such pull request, with the event appended after the prompt.

An organization with several Docusaurus sites sends this body once per repository from its own server, each a `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own config: a site with one locale gets a plain `pathname` mapping, and one that already swizzled `BlogPostItem` gets the comments added inside that file instead of a second wrapper.

## Why run it on Rush?

Comment widgets are usually added by pasting a script tag into a swizzled component and discovering later that the list page shows a widget per excerpt, that dark mode shows a white box, or that each locale opened its own discussion. The agent reads the color mode config, the eight locales and the existing swizzles first and builds the component from them, then loads a post in both modes to see the iframe it asked for.

The lint, build and browser checks stay with the run and are in the pull request, so the reviewer sees the widget in both themes before enabling Discussions. The same request runs across every Docusaurus site a team keeps, each run reading that site's own config.

## Frequently asked questions

### Will comments show up on the blog index page?

No. The wrapper reads `isBlogPostPage` from `useBlogPost()` and renders the comments component only when it is true, so `/blog` and the tag pages keep showing excerpts with the site's read-more button and nothing below them.

### Why mapping specific instead of pathname?

Because the site serves eight locales under their own `baseUrl`, and `pathname` would open a separate discussion for `/ja/blog/…` and `/blog/…`. The component passes the permalink without its locale prefix as `term`, so a post has one discussion whatever language the reader chose. A site with one locale can switch to `pathname` by changing one prop.

### Does the widget follow the dark mode toggle?

Yes. The component reads `useColorMode().colorMode` and passes `light` or `dark` as the `theme` prop; when the prop changes, `@giscus/react` sends the new theme to the embed with `postMessage`, so the widget switches without reloading the comments.

### What has to be done by hand?

Installing the giscus GitHub App on the repository, turning on Discussions and choosing the category: those are repository settings a person with admin rights sets on github.com. The pull request lists the three steps and where giscus shows the `repoId` and `categoryId` to paste into `docusaurus.config.ts`.

### Can I turn comments off for one post?

Yes. The component checks the post's front matter for `comments: false` and renders nothing when it finds it, so an announcement that should not take comments opts out with one line. No existing post is edited by the run.

## More Docusaurus jobs

- [Add i18n to a Docusaurus Site](https://getrush.ai/run/add-i18n/docusaurus/)
- [Add Lighthouse CI to a Docusaurus Site](https://getrush.ai/run/add-lighthouse-ci/docusaurus/)
- [Find and Fix Broken Links in a Docusaurus Site](https://getrush.ai/run/add-link-checking/docusaurus/)

## The same job on other stacks

- [Add Giscus Comments to an Eleventy Blog](https://getrush.ai/run/add-giscus-comments/eleventy/)
- [Add Giscus Comments to a Gatsby Blog](https://getrush.ai/run/add-giscus-comments/gatsby/)
- [Add Giscus Comments to a Hugo Blog](https://getrush.ai/run/add-giscus-comments/hugo/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
