# Add Giscus Comments to an mdBook

Yes. An agent adds a giscus thread under every chapter of your mdBook through additional-js, follows the theme switcher, skips the print page and opens a PR.

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

## What the agent does

The agent reads the book's configuration and its build before adding a script. In a book like rust-lang/nomicon, `book.toml` sets the title and description, an `[output.html]` table with `additional-css = ["theme/nomicon.css"]`, a `git-repository-url` and a block of `[output.html.redirect]` entries for chapters that moved under `vec/` and `arc-mutex/`, and a `[rust]` table with `edition = "2024"`. `theme/` holds only `nomicon.css`, so the book runs the default templates rather than an overridden `index.hbs`. `src/SUMMARY.md` lists about fifty chapters. `.github/workflows/main.yml` pins `MDBOOK_VERSION: 0.5.1`, installs it from the release tarball, runs `mdbook test` on a nightly toolchain and a link check with the `linkcheck.sh` script from the Rust repository, and the README documents `mdbook build` and `mdbook test`. In mdBook 0.5 the page template puts the chapter inside `<div id="content"><main>`, sets the theme as a class on the `html` element, `light`, `rust`, `coal`, `navy` or `ayu`, switches it by editing that class list, and loads every `additional-js` file at the end of the body.

The comments come from giscus, which stores each thread as a GitHub Discussion in the book's repository, so the change is a client script and nothing on a server. Rather than copy `index.hbs` out of mdBook, which would have to be redone on every mdBook upgrade, the agent adds `theme/giscus.js` to a new `additional-js` list in `book.toml` and `theme/giscus.css` to the existing `additional-css` one. The script runs after the page loads, skips `print.html`, which concatenates every chapter and should carry no fifty threads, and appends a `<script src="https://giscus.app/client.js">` element to `#content main` with the attributes giscus reads: `data-repo`, `data-repo-id`, `data-category`, `data-category-id`, `data-mapping="pathname"` so each chapter maps to its own discussion, `data-strict="1"`, `data-reactions-enabled`, `data-input-position="bottom"`, `data-lang`, `crossorigin="anonymous"` and a `data-theme` chosen from the book's current class.

The theme is the part that is easy to get wrong. The script maps the book's five themes to giscus's `light` and `dark`, and because mdBook switches themes by changing the class on the `html` element without reloading, it installs a `MutationObserver` on that element's `class` attribute and, on each change, posts a `setConfig` message with the new theme to the giscus iframe, the way giscus documents. The stylesheet adds space above the thread and keeps it inside the chapter's width. The ids are the one input the agent cannot invent: `data-repo-id` and `data-category-id` are the repository's GraphQL node id and the id of a Discussions category. When Discussions are enabled on the repository, the agent reads both with a GraphQL query through the repository's GitHub access and fills them in; when they are not, it leaves the two attributes as named placeholders and the pull request says to enable Discussions, install the giscus app and paste the ids from giscus.app.

The check is a build and a look. The agent installs mdBook at the version the workflow pins, runs `mdbook build`, opens `book/intro.html` in its browser and confirms the script element sits under the chapter and the giscus iframe loads, flips the theme menu to `coal` and `light` and watches the thread repaint, opens `book/print.html` and confirms nothing was added, and keeps a screenshot of each. It runs `mdbook test` too, which exercises the Rust code blocks and is unaffected by a script, so the pull request shows the workflow's own checks still pass.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add giscus comments to this mdBook. Read book.toml, src/SUMMARY.md, the theme directory, README.md and .github/workflows first. Do not override index.hbs: add theme/giscus.js through an additional-js list in book.toml and theme/giscus.css through additional-css. The script must append the giscus client script to the chapter's main element with pathname mapping, strict matching and reactions, skip print.html, pick the giscus theme from the class mdBook sets on the html element, and update the iframe through a setConfig message when that class changes. If GitHub Discussions are enabled, read the repository node id and the discussion category id through the GitHub GraphQL API and fill in data-repo-id and data-category-id; otherwise leave named placeholders and say what to do in the pull request. Install mdBook at the version the workflow pins, run mdbook build and mdbook test, open a chapter in the browser, switch themes and check the print page, and open a pull request with the output and screenshots.",
  "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 adds `theme/giscus.js` and `theme/giscus.css` and changes `book.toml` by one new key and one extended list. Its description quotes the `mdbook build` and `mdbook test` output, names the version it installed, shows a chapter with the thread in two themes and the print page without it from the run's record, and either shows the two ids it read from GitHub or lists the three steps left for the maintainer.

A reviewer reads the script, which is short, and the attributes, which decide where comments land: `pathname` mapping means a chapter that moves gets a fresh thread, and the redirect table in `book.toml` already records which chapters have moved before. The workflow runs the same build and tests on the pull request, so the merge question is whether the book wants comments at all and in which category.

## Run it on every book repository

A team that publishes several books from one organization sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming one repository in `resources` with 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 `book.toml`: a book that already overrides `index.hbs` gets the script tag in that template instead of a second script, and a book with a custom theme list gets its themes mapped rather than the five defaults.

An automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request moves or renames a chapter, check that book.toml gains a redirect for it and note that its giscus thread will start fresh, as a review" keeps the threads attached to the right pages. The trigger adds the pull request after the prompt and fills in nothing else.

## Why run it on Rush?

The script is short, and the ways to get it wrong are all visible only in a browser: a thread under the print page, a dark box on a light chapter after a theme switch, ids from the wrong repository. The agent builds the book at the pinned version in its own sandbox, opens real chapters, switches themes and reads the print page, and keeps the commands and screenshots in the run's record.

Doing it through `additional-js` instead of a template override is the decision that keeps the change cheap later: the next mdBook release updates `index.hbs` without a merge conflict, and the agent reads the template only to learn where the chapter sits and how the theme is stored, not to copy it.

## Frequently asked questions

### Why not override index.hbs?

A copied `index.hbs` freezes the template at one mdBook version, and the book's workflow pins a version it will move again. `additional-js` loads the script on every page without copying the template, so a future mdBook upgrade changes nothing in the book's own files.

### Does the thread follow the theme switcher?

Yes. mdBook stores the theme as a class on the `html` element and changes it in place, so the script watches that attribute with a `MutationObserver` and sends giscus a `setConfig` message with `light` or `dark`. The run's screenshots show the same chapter in two themes.

### Where do data-repo-id and data-category-id come from?

From GitHub: the repository's node id and the id of a Discussions category, which giscus.app shows after the giscus app is installed. If Discussions are already on, the agent reads both through the GraphQL API and fills them in; if not, it leaves named placeholders and the pull request lists the steps.

### What happens when a chapter is renamed?

With `pathname` mapping, the thread belongs to the page's path, so a renamed chapter starts a new discussion and the old one stays attached to the redirect. Switching to `data-mapping="title"` keeps a thread across a rename at the cost of colliding on duplicate titles; the pull request explains the trade.

### Does mdbook test change?

No. `mdbook test` compiles and runs the Rust code blocks and never loads the rendered HTML, so a script in `additional-js` cannot affect it. The agent runs it anyway so the pull request shows the workflow's checks still pass.

## More mdBook jobs

- [Add i18n to an mdBook Site](https://getrush.ai/run/add-i18n/mdbook/)
- [Add Last Updated Dates to an mdBook Site](https://getrush.ai/run/add-last-updated-dates/mdbook/)
- [Add External Link Checking to an mdBook](https://getrush.ai/run/add-link-checking/mdbook/)

## The same job on other stacks

- [Add Giscus Comments to a MkDocs Material Site](https://getrush.ai/run/add-giscus-comments/mkdocs/)
- [Add Giscus Comments to a Pelican Blog](https://getrush.ai/run/add-giscus-comments/pelican/)
- [Add Giscus Comments to a Starlight Site](https://getrush.ai/run/add-giscus-comments/starlight/)

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