All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading