All jobs

Add Giscus Comments to a Gatsby Blog

Yes. An agent adds a Giscus component under each post in the blog template, reads its settings from siteMetadata, builds the site 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 posts are rendered before it adds anything under them. In a blog shaped like gatsbyjs/gatsby-starter-blog, package.json pins gatsby 5 with React 18, gatsby-transformer-remark, gatsby-plugin-feed, gatsby-plugin-image and gatsby-plugin-manifest, with Prettier as the only dev dependency and a test script that exits with a reminder to write tests. gatsby-config.js holds siteMetadata with the title, author, description, siteUrl and social handle, and gatsby-node.js creates one page per Markdown file in content/blog with src/templates/blog-post.js, passing the previous and next post ids. That template renders the post inside Layout, with Bio in the footer and a previous and next navigation below the article. src/components/seo.js reads siteMetadata through useStaticQuery, which is the pattern the agent reuses for the comment settings. There are three sample posts and no comments anywhere.

It adds src/components/comments.js, a component that appends Giscus's https://giscus.app/client.js script in a useEffect on a ref'd div, with the data-repo, data-repo-id, data-category, data-category-id, data-mapping, data-strict, data-reactions-enabled, data-emit-metadata, data-input-position, data-theme, data-lang and crossorigin attributes that giscus.app generates, and cleans the script up on unmount so client-side navigation between posts does not stack two comment boxes. The repository, category and their ids come from a new comments block in siteMetadata, read with useStaticQuery the way seo.js reads the site title, and the agent adds type Comments to the schema customisation in gatsby-node.js so a site without the block builds instead of failing the query. The pathname mapping is used so each post's thread is keyed by its slug, which the feed and the page paths already use.

In src/templates/blog-post.js the component goes between the article's footer and the previous and next navigation, with the post's fields.slug passed as the term so the thread survives a title change. The agent does not add @giscus/react, since the script tag needs no dependency and the starter has none beyond Gatsby's own; the pull request notes the package as the alternative. The ids themselves cannot be made up: data-repo-id and data-category-id come from giscus.app after the Giscus app is installed on the repository and Discussions are enabled, so the agent leaves them empty in gatsby-config.js, has the component render nothing until they are set, and writes those two steps in the pull request description.

The agent runs npm run format so Prettier is happy, npm run build, and npm run serve, then opens a post in the sandbox browser to confirm the page renders with the placeholder and no console error, and screenshots it for the pull request. With ids filled in from a test repository of its own it would show the thread; without them it shows the build passing and the component mounting.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Giscus comments under each blog post of this Gatsby site and open a pull request. Read package.json, gatsby-config.js, gatsby-node.js, src/templates/blog-post.js, src/components/seo.js, src/components/layout.js, src/pages/index.js and the posts under content/blog first. Add src/components/comments.js that injects the giscus.app client script in a useEffect on a ref'd div with the data-repo, data-repo-id, data-category, data-category-id, data-mapping pathname, data-strict, data-reactions-enabled, data-emit-metadata, data-input-position, data-theme, data-lang and crossorigin attributes, removes the script on unmount, and renders nothing until the ids are set. Read the settings from a new comments block in siteMetadata through useStaticQuery as seo.js does, and add the matching type to createSchemaCustomization in gatsby-node.js so the query works when the block is absent. Place the component in blog-post.js between the article footer and the previous and next navigation. Do not add a dependency. Run npm run format and npm run build, serve the site, open a post in the browser, and paste the build output and a screenshot in the pull request along with the two steps the reader must do on giscus.app to get the repository and category ids.",
  "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 with a new src/components/comments.js, a few lines in src/templates/blog-post.js, a comments block in gatsby-config.js with the repository name filled in and the ids left empty, and the schema type in gatsby-node.js. The description shows the gatsby build summary, a screenshot of a post page from gatsby serve, and the two steps to take on giscus.app.

The starter has no GitHub Actions workflow, so the build output and the screenshot are the proof, with the full commands in the run's transcript. A reviewer who wants a check adds a workflow that runs npm run build on pull requests.

A reviewer installs the Giscus app on the repository, enables Discussions, pastes the two ids into gatsby-config.js and rebuilds, then checks that a comment posted on one post does not appear on another, which the pathname mapping guarantees, and that the theme matches the site. Then they decide whether to switch to data-theme preferred_color_scheme.

Run it on every new blog repository

A team that runs a blog per product from the same starter sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own template and siteMetadata, so a blog whose posts render through a different template gets the component placed there, and each opens its own pull request with the giscus.app steps for its own repository.

A webhook_url on the key reports run.completed per run with data.session_url, from which the pull request link is read.

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

Why run it on Rush?

Adding a third-party widget to a static site is easy to get almost right: the script loads twice after a client-side navigation, the GraphQL query fails the build on a site without the config block, or the wrong mapping gives two posts one thread. In a Rush sandbox the agent builds the site, serves it, opens a post in a real browser and reads the console, and that build output and screenshot stay in the run with the pull request.

The same request runs on every Gatsby blog a team owns without a local Node toolchain or a Gatsby cache to clear, and the sandbox parks when it is done, so a follow-up to switch the theme or move to @giscus/react wakes it where it stopped.

Frequently asked questions

Why does the agent leave the ids empty?

Because data-repo-id and data-category-id are issued by giscus.app for your repository once the Giscus app is installed and Discussions are on, and inventing them would render a broken widget. The component renders nothing until both are set, so the site builds and ships unchanged until you fill them in.

Should I use @giscus/react instead?

It wraps the same script in a component with typed props. The starter has no dependencies beyond Gatsby's, and the script tag with a cleanup on unmount does the job, so the pull request keeps it dependency-free and names the package as the alternative.

Does the comment thread follow a post if I rename it?

With data-mapping set to pathname the thread is keyed by the post's URL, which comes from the Markdown folder name through createFilePath in gatsby-node.js, not from its title. Renaming the folder would start a new thread; changing the title would not.

Will comments show on the index page?

No. The component is placed only in src/templates/blog-post.js, so the post list in src/pages/index.js and the RSS feed are unchanged.

More Gatsby jobs

The same job on other stacks

Keep reading