# Add Giscus Comments to an Eleventy Blog

Yes. An agent adds the Giscus widget to your Eleventy post layout from a partial, keeps its settings in your site data, and lets a post opt out in front matter.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how the site is put together before adding anything. In a blog like 11ty/eleventy-base-blog, `package.json` pins `@11ty/eleventy` ^3.1.7 as an ES module project on Node 18 or newer (`.nvmrc` says 22), and `eleventy.config.js` sets `content` as the input folder with `../_includes` and `../_data` beside it. The same file registers two bundles with `addBundle`: a `css` bundle and a `js` bundle that collects the content of every `<script>` element on a page into one file under `dist`, with a comment in `_includes/layouts/base.njk` saying that a `<script eleventy:ignore>` tag is the way to keep one out of it. `content/blog/blog.11tydata.js` gives every file in `content/blog` the `posts` tag and the `layouts/post.njk` layout, and `_data/metadata.js` holds the site title, `url`, `language` and author. There is no comment system anywhere.

Giscus stores comments in GitHub Discussions, and its script tag needs four values the agent cannot make up: the repository as `owner/name`, its `repoId`, a discussion category and that category's `categoryId`. The agent adds a `giscus` object to `_data/metadata.js` with `repo` prefilled from the repository it cloned, `repoId` and `categoryId` left as empty strings behind a comment that says to copy them from the giscus.app configuration page once Discussions are on and the giscus app is installed, `category` set to `Announcements` as giscus recommends, `mapping` set to `pathname`, `lang` taken from `metadata.language`, `theme` set to `preferred_color_scheme` and reactions enabled.

The widget itself lives in a new `_includes/comments.njk`: a `<section class="comments">` with a heading and the `https://giscus.app/client.js` script tag carrying the `data-` attributes from the metadata, `crossorigin="anonymous"` and `async`. The tag gets the `eleventy:ignore` attribute so the `js` bundle leaves the external script where it is instead of trying to inline it. `post.njk` includes the partial after the previous and next links, inside a condition that checks `metadata.giscus.repoId` is set and the post has not declared `comments: false` in its front matter. `_data/eleventyDataSchema.js` already validates `draft` with a zod schema and throws on a wrong type; the agent adds `comments` as an optional boolean to the same schema so a typo in front matter fails the build the way a bad `draft` does. A few lines in `css/index.css` give the section the same top margin as the metadata list.

Then it proves the change in the sandbox: `npm install`, `npx @11ty/eleventy`, and a check that `_site/blog/firstpost/index.html` contains the script tag with the data attributes while `_site/about/index.html` and the home page do not. It runs `npm run build-ghpages` as well, because that script passes `--pathprefix=/eleventy-base-blog/` and the widget must not be affected by the HTML base plugin rewriting URLs; the giscus script is an absolute URL, so it is not. It changes no post, no feed and no other layout, and opens a pull request with the build output in its description.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Giscus comments to this Eleventy blog. Read eleventy.config.js, the layouts in _includes/layouts and _data/metadata.js first. Keep the Giscus settings in the site metadata (repo, repoId, category, categoryId, mapping, lang, theme), prefill repo from this repository and leave the two ids empty with a comment on where to copy them from. Render the widget from a partial included at the end of the post layout only, let a post opt out with comments: false in its front matter and validate that field in the data schema, and make sure the JS bundle plugin leaves the external script tag alone. Build the site and confirm the widget appears on blog posts and nowhere else. Open a pull request.",
  "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 on its own branch that adds `_includes/comments.njk`, changes `_data/metadata.js`, `_includes/layouts/post.njk`, `_data/eleventyDataSchema.js` and `css/index.css`, and touches nothing else. The description names the two values you still have to paste in, shows the lines of the built post page that carry the widget, and shows that the about page and the index do not.

The run's record keeps the `npm install` and both Eleventy builds with their output, so a reviewer can see that the build passed with the default path and with the GitHub Pages path prefix, and that the `js` bundle file in `dist` did not swallow the giscus tag.

Before merging, a reviewer turns on Discussions in the repository settings, installs the giscus GitHub app on that one repository, creates or picks an Announcements category, copies `repoId` and `categoryId` into `_data/metadata.js`, and decides whether `pathname` is the right mapping: it ties a thread to the URL path, which survives a domain move but not a slug change.

## Run it on every blog you set up

Start it from a terminal with one `POST /o/{org}/sessions` carrying this body and the repository in `resources`, then close the laptop; the agent keeps working in its sandbox. When the pull request is up and you want a change, a follow-up with `POST /o/{org}/sessions/{id}/messages` wakes the parked sandbox where it left off: switch the mapping to `title`, add the widget to pages tagged `notes` as well, or move the section above the previous and next links.

If you maintain several Eleventy sites, a script can send one request per repository, each run in a sandbox of its own with its own pull request. Give each request a `request_id`, a UUID you keep per site, so running the script twice returns the run it already started instead of opening a second pull request on the same repository.

## Why run it on Rush?

Adding a comment widget by hand is quick until the bundle plugin inlines the script, the widget shows up on the about page, or a post that should stay quiet cannot opt out. The agent reads the configuration first, puts the settings where the rest of the site data lives, validates the new front matter field like the existing one, and builds the site twice to show the widget lands only where it should.

The sandbox runs the real Eleventy build with the output kept in the run's record, so the pull request carries evidence rather than a promise. Nothing about your GitHub account is needed for the build: the two Discussions ids are the one part that stays with you, and the page says exactly where they go.

## Frequently asked questions

### Do I have to give the agent my GitHub Discussions ids?

No. The agent cannot read them and does not ask for them. It leaves `repoId` and `categoryId` empty in `_data/metadata.js` with a comment pointing at the giscus.app configuration page, and the post layout renders nothing until both are filled in, so merging the pull request early is safe.

### Will comments show up on the about page or the home page?

No. The partial is included from `layouts/post.njk` only, which `content/blog/blog.11tydata.js` applies to files in the blog folder. Pages that use `layouts/home.njk` or `layouts/base.njk` directly are untouched, and the agent checks the built HTML of both to confirm it.

### Does this work with the GitHub Pages build that uses a path prefix?

Yes. The giscus script is loaded from an absolute `https://giscus.app` URL, so the HTML base plugin does not rewrite it when `npm run build-ghpages` passes `--pathprefix`. The agent runs that build too and reports the result.

### Can readers comment without a GitHub account?

They can read every thread without one, but posting a comment or a reaction requires signing in to GitHub through the widget, because each thread is a GitHub Discussion in your repository. If you need anonymous comments, Giscus is the wrong tool and the agent will say so if you ask.

### How does a single post turn comments off?

Add `comments: false` to that post's front matter. The post layout checks the field before including the partial, and the data schema in `_data/eleventyDataSchema.js` rejects anything that is not a boolean, so `comments: no` fails the build instead of silently showing the widget.

## More Eleventy jobs

- [Set Up GitHub Actions CI for an Eleventy Site](https://getrush.ai/run/add-github-actions-ci/eleventy/)
- [Add i18n to an Eleventy Blog](https://getrush.ai/run/add-i18n/eleventy/)
- [Show a Last Updated Date from Git History on Eleventy Posts](https://getrush.ai/run/add-last-modified-dates/eleventy/)

## The same job on other stacks

- [Add Giscus Comments to a Gatsby Blog](https://getrush.ai/run/add-giscus-comments/gatsby/)
- [Add Giscus Comments to a Hugo Blog](https://getrush.ai/run/add-giscus-comments/hugo/)
- [Add Giscus Comments to a Jekyll Site](https://getrush.ai/run/add-giscus-comments/jekyll/)

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