All jobs

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

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

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

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

The same job on other stacks

Keep reading