# Add Giscus Comments to a Starlight Site

Yes. An agent overrides Starlight's Footer with a giscus thread that follows the site's theme, lets a page opt out in frontmatter, builds it, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-giscus-comments/starlight/). 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 site is configured and which component owns the bottom of a page before adding anything. In a site started from the `examples/basics` project in withastro/starlight, `package.json` depends on `@astrojs/starlight` ^0.42.7, `astro` ^7.2.10 and `sharp`, and `astro.config.mjs` calls `starlight()` with a title, a GitHub social link and a two-group sidebar; `src/content.config.ts` defines the `docs` collection with `docsLoader()` and `docsSchema()`. There are three pages: `index.mdx` with `template: splash` and a hero, `guides/example.md` and `reference/example.md`. Starlight's overrides reference says the `Footer` component renders at the bottom of the main column and by default shows `EditLink`, `LastUpdated` and `Pagination`, and `Page.astro` in the package renders it for every page, so a comment thread belongs in an override of `Footer`, not in a layout the site does not own.

The override follows the pattern in Starlight's own guide. `src/components/Footer.astro` imports the default from `@astrojs/starlight/components/Footer.astro`, renders it, and then renders a new `src/components/Comments.astro` beneath it; `astro.config.mjs` gains `components: { Footer: './src/components/Footer.astro' }`. The giscus block is the script tag from giscus.app with `data-repo`, `data-repo-id`, `data-category`, `data-category-id`, `data-mapping` set to `pathname`, `data-strict`, `data-reactions-enabled`, `data-emit-metadata`, `data-input-position`, `data-lang`, `crossorigin` of `anonymous` and `async`. The repo and category ids come from giscus's configurator and are not derivable from the repository, so the component reads them from `PUBLIC_GISCUS_REPO`, `PUBLIC_GISCUS_REPO_ID`, `PUBLIC_GISCUS_CATEGORY` and `PUBLIC_GISCUS_CATEGORY_ID` through `import.meta.env`, renders nothing when any is missing, and a `.env.example` documents them; giscus also requires the repository to be public with Discussions enabled and the giscus app installed, which the pull request lists as the three steps a person does on GitHub.

Theme sync is the part a pasted snippet gets wrong. Starlight sets `data-theme` on `<html>` to `light` or `dark` from an inline script in `ThemeProvider.astro`, and `ThemeSelect.astro` updates the same attribute when a visitor changes the picker. The component sets `data-theme` on the giscus script to match the attribute at load, and a small client script attaches a `MutationObserver` to `document.documentElement` for `data-theme` changes and posts `{ giscus: { setConfig: { theme } } }` to the `iframe.giscus-frame` with `https://giscus.app` as the target origin, which is the message shape giscus documents for changing the theme without reloading. Per-page opt out uses the schema: `docsSchema({ extend: z.object({ comments: z.boolean().optional() }) })` in `content.config.ts`, and the component reads `Astro.locals.starlightRoute.entry.data.comments` and also skips pages whose `template` is `splash`, so the landing page stays clean without a frontmatter line.

Verification is a build and a look at the output. In the sandbox the agent runs `npm install`, `npx astro check` and `npm run build` with the four variables set to placeholder values, then greps `dist/guides/example/index.html` for the giscus script and its `data-mapping="pathname"` attribute and confirms `dist/index.html` has none, and repeats the build with the variables unset to confirm the component renders nothing. It adds a section to `README.md` on where the ids come from and how to turn comments off per page, and opens the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add giscus comments to this Starlight site. Read package.json, astro.config.mjs, src/content.config.ts, the three pages under src/content/docs and README.md first, and read Starlight's overriding-components guide and the Footer entry of its overrides reference. Add src/components/Footer.astro that renders the default Footer from @astrojs/starlight/components/Footer.astro followed by a new src/components/Comments.astro, and register it under components.Footer in astro.config.mjs. In Comments.astro render the giscus script tag with data-mapping pathname, crossorigin anonymous and async, reading data-repo, data-repo-id, data-category and data-category-id from PUBLIC_GISCUS_REPO, PUBLIC_GISCUS_REPO_ID, PUBLIC_GISCUS_CATEGORY and PUBLIC_GISCUS_CATEGORY_ID via import.meta.env, rendering nothing when any is missing, and add a .env.example naming them. Set the script's data-theme from the html element's data-theme attribute and add a client script with a MutationObserver on that attribute that posts { giscus: { setConfig: { theme } } } to iframe.giscus-frame with target origin https://giscus.app. Extend docsSchema with an optional boolean comments field, skip rendering when it is false or when the page template is splash, and document both in README.md along with the three GitHub prerequisites. Run npm install, npx astro check and npm run build with placeholder values, show that dist/guides/example/index.html contains the giscus script and dist/index.html does not, build again with the variables unset to show nothing renders, then open a pull request that pastes those checks.",
  "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

What comes back is a pull request that adds `src/components/Footer.astro`, `src/components/Comments.astro` and `.env.example`, and changes `astro.config.mjs`, `src/content.config.ts` and `README.md`. The description pastes the `astro check` and `astro build` output, the grep showing the giscus script in the guide page's HTML and its absence from the landing page, and the second build showing nothing rendered without the variables.

The run's record holds the install, the type check and both builds. The three content pages are untouched, so `comments: false` is shown in the README rather than added to any page, and the default footer still renders its edit link, last-updated date and pagination above the thread.

Before merging, a reviewer creates the Discussions category on GitHub, installs the giscus app, copies the four values from giscus's configurator into the hosting provider's environment, and decides whether `data-mapping` should stay `pathname` or move to `og:title` if the site's URLs are expected to change.

## Run it on every new docs site

A team that keeps a Starlight site per product starts one run per repository from its own server: one `POST /o/{org}/sessions` each, 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 rather than a second pull request. Each run reads that site's own `astro.config.mjs`, so a site that already overrides `Footer` gets the thread added inside its component and a site with `locales` gets `data-lang` set from the current locale.

Afterwards, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request adds a page under src/content/docs with template splash or without a title, say whether comments will render on it and comment if that looks unintended" catches the landing pages that should stay clean. The trigger adds the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.

## Why run it on Rush?

Pasting the giscus snippet into a Starlight site is five minutes; making it behave is the work, and each piece comes from reading the framework: the right component to override, how Starlight stores the active theme, the message shape giscus accepts for a theme change, and how to extend the frontmatter schema so a page can opt out. The agent reads those sources at the installed version and builds the site to show the thread lands on the pages it should.

In its own sandbox the agent runs the type check and two builds, and the run keeps the output and the HTML excerpts for the pull request. For a team with many documentation sites, each gets its own run and its own pull request with the override fitted to that site's configuration.

## Frequently asked questions

### Where do the repo and category ids come from?

From giscus's configurator at giscus.app, after the repository is public, has Discussions enabled and has the giscus app installed. They cannot be read from the repository, which is why the component takes them from `PUBLIC_GISCUS_*` variables and renders nothing until they are set, so a preview build without them is still a clean site.

### Does the thread follow the light and dark toggle?

Yes. Starlight writes `data-theme` on `<html>` and updates it from its theme picker, so the component reads it at load and a `MutationObserver` posts a `setConfig` message with the new theme to the giscus iframe when it changes. No page reload is needed.

### How do I turn comments off on one page?

Add `comments: false` to that page's frontmatter; the schema extension makes the field optional and typed. Pages using the `splash` template never render the thread, so the landing page needs no line at all.

### Why override Footer and not MarkdownContent?

The overrides reference places `Footer` at the bottom of the main column, after the content, which is where a comment thread reads naturally, and the override keeps the default footer by rendering it first. Overriding `MarkdownContent` would wrap the article itself and put the thread above the edit link and pagination.

## More Starlight jobs

- [Add i18n to a Starlight Docs Site](https://getrush.ai/run/add-i18n/starlight/)
- [Check for Broken Links in a Starlight Docs Site](https://getrush.ai/run/add-link-checking/starlight/)
- [Add llms.txt to a Starlight Docs Site](https://getrush.ai/run/add-llms-txt/starlight/)

## The same job on other stacks

- [Add Giscus Comments to a VitePress Blog](https://getrush.ai/run/add-giscus-comments/vitepress/)
- [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/)

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