# Add Giscus Comments to a VitePress Blog

Yes. An agent adds a giscus thread under each post of your custom-theme VitePress blog, client-only, matching the colour scheme, with an opt-out, and opens a PR.

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

## What the agent does

The agent reads the theme before it adds a component, because a VitePress site with a custom theme has no default layout slots to hook into. In a blog laid out like vuejs/blog, `.vitepress/theme/index.ts` exports only `Layout`, and `Layout.vue` chooses between `Home.vue`, `NotFound.vue` and `Article.vue` by `frontmatter.index` and `page.isNotFound`. `Article.vue` renders the post through `<Content>` and a footer with next and previous links from `posts.data.ts`, a `createContentLoader('posts/*.md')` loader. `.vitepress/config.ts` sets `cleanUrls: true`, a `head` with Twitter meta and a Fathom script, and `buildEnd: genFeed` for the RSS file. Dark mode comes from Tailwind's `dark:` classes with no `darkMode` setting in `postcss.config.js`, so it follows `prefers-color-scheme` and there is no toggle to listen to. `package.json` pins `pnpm@9.8.0`, `vitepress` on the 1 line and `vue` on the 3 line, and there are sixteen posts under `posts/`.

Then it adds the component. `@giscus/vue` goes in as a dependency, and `.vitepress/theme/Comments.vue` wraps `<Giscus>` with `repo`, `repoId`, `category`, `categoryId` and `mapping="pathname"`, `strict="1"`, `reactionsEnabled="1"`, `inputPosition="top"`, `theme="preferred_color_scheme"`, `lang="en"` and `loading="lazy"`; the ids come from the prompt, since they are issued by giscus.app once Discussions are enabled and the giscus app is installed on the repository, which the agent cannot do from a sandbox. `mapping="pathname"` works with `cleanUrls`, because the thread key is the post's path such as `/posts/vitepress-1.0`, which does not change if the title does. The component is rendered inside `<ClientOnly>`, since giscus registers a custom element that cannot run in VitePress's server render.

`Article.vue` gets `<Comments>` after `<Content>` and before the footer, behind `v-if="frontmatter.comments !== false"` from `useData()`, so a post can opt out with `comments: false` in its frontmatter; the agent documents that key in a comment in `posts.data.ts` rather than extending the `Post` interface, since the loader does not need it. The giscus theme is `preferred_color_scheme` because the site has no theme toggle; if one is added later, the component accepts a `theme` prop that follows it.

Then it builds and looks. `pnpm install`, `pnpm build` (`vitepress build`), and a check that `.vitepress/dist/posts/vitepress-1.0.html` contains no giscus markup, which is correct for a client-only component, followed by `pnpm preview` and a visit to that post in the sandbox browser to see the `giscus-frame` iframe load under the article, with a screenshot kept with the run. `genFeed` still runs at `buildEnd` and `feed.rss` is unchanged, which the agent checks by diffing it against a build from `main`.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add giscus comments to this VitePress blog with a custom theme. Read package.json, .vitepress/config.ts, .vitepress/genFeed.ts, .vitepress/theme/index.ts, Layout.vue, Article.vue, Home.vue, posts.data.ts, postcss.config.js and the frontmatter of two posts first. Add @giscus/vue and a Comments.vue component in the theme that renders Giscus inside ClientOnly with repo your-org/your-blog, repoId R_XXXX, category Announcements, categoryId DIC_XXXX, mapping pathname, strict on, reactions on, input position top, theme preferred_color_scheme, lang en and lazy loading. Render it in Article.vue after the content unless the post's frontmatter sets comments to false. Run pnpm build, confirm the built post HTML has no giscus markup, then run pnpm preview and open one post in the browser to confirm the giscus iframe loads, with a screenshot. Confirm feed.rss is unchanged. Open a pull request with the output and the screenshot.",
  "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 changes `package.json`, `pnpm-lock.yaml` and `.vitepress/theme/Article.vue`, and adds `.vitepress/theme/Comments.vue`. Its description shows the build output, the screenshot of a post with the thread loaded, the empty `feed.rss` diff, and the frontmatter key a post uses to opt out.

There is no workflow in the repository, so no check runs on the pull request; `vercel.json` suggests Vercel builds the site, and its preview deployment is where a reviewer sees the thread on the real domain, which is also where giscus's origin check matters.

Before merging, a reviewer confirms the `repoId` and `categoryId` match the giscus.app configuration for the repository, decides whether the home page or the 404 page should ever show a thread (they do not here, since only `Article.vue` renders it), and decides whether `strict` matching is wanted, which binds each thread to the page's exact path.

## Run it on every new blog or docs site

A team that runs a VitePress site per product starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with that repository in `resources`, that site's giscus ids in `input`, 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 theme: a site on the default theme gets the component in the `doc-after` layout slot through `enhanceApp`, and one with an `appearance` toggle gets the giscus theme bound to `isDark` from `useData()`.

After the merge, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request adds a post under posts/, say whether comments will render on it and whether the frontmatter opts out" catches announcement posts that should stay quiet. The trigger adds the pull request after the prompt; only pushes by an owner, member or collaborator fire it, never a fork's.

## Why run it on Rush?

The snippet giscus gives you is five lines; fitting it to a custom VitePress theme is the work: finding the component that renders a post, keeping the custom element out of the server render, matching the site's colour scheme, and choosing a thread key that survives a title change. The agent reads the theme at its installed version, makes those choices from what it finds, and builds the site to show the thread lands on posts and nowhere else.

In its own sandbox the agent runs the build and the preview and opens a post in a real browser, so the pull request carries a screenshot of the loaded thread rather than a promise. For a team with several sites, each gets its own run and its own pull request, fitted to its own theme.

## Frequently asked questions

### Why ClientOnly?

VitePress renders each page to static HTML at build time, and `@giscus/vue` registers the `giscus-widget` custom element, which needs a browser. Wrapping it in `<ClientOnly>` leaves it out of the server render and mounts it on the client, which is why the built HTML has no giscus markup and the check is done in a browser.

### Does the thread follow dark mode?

This theme has no toggle; dark styles come from Tailwind's media strategy. `theme="preferred_color_scheme"` makes giscus follow the same system setting. A site with a toggle passes a computed theme prop instead, and the agent says so in the component.

### What do I need to set up before running this?

Discussions enabled on the repository, the giscus GitHub app installed on it, and the ids from giscus.app for the repository and the category. Those steps need a person on github.com; the run takes the ids in its prompt.

### Will the RSS feed change?

No. `genFeed` renders posts with `createContentLoader` at `buildEnd`, independent of the theme components, and the agent diffs `feed.rss` against a build from `main` to show it.

## More VitePress jobs

- [Add Last Updated Dates to a VitePress Blog](https://getrush.ai/run/add-last-updated-dates/vitepress/)
- [Add Lighthouse CI to a VitePress Docs Site](https://getrush.ai/run/add-lighthouse-ci/vitepress/)
- [Add Link Checking to a VitePress Site](https://getrush.ai/run/add-link-checking/vitepress/)

## The same job on other stacks

- [Add Giscus Comments to a Zola Blog](https://getrush.ai/run/add-giscus-comments/zola/)
- [Add Giscus Comments to an Astro Blog](https://getrush.ai/run/add-giscus-comments/astro/)
- [Add Giscus Comments to a Docusaurus Blog](https://getrush.ai/run/add-giscus-comments/docusaurus/)

## 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/)
