All jobs

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

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

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

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

The same job on other stacks

Keep reading