What the agent does
The agent reads the book's structure first. In a book laid out like rust-lang/nomicon, book.toml has a [book] table, an [output.html] table with additional-css = ["theme/nomicon.css"] and a git-repository-url, a long [output.html.redirect] table for chapters that moved into the vec/ and arc-mutex/ directories, and [rust] edition = "2024"; there is no [preprocessor.*] table. src/SUMMARY.md lists 63 chapters, most of them nested under twelve top-level entries. The chapters are uneven: src/ffi.md runs to 19 second-level headings and 6 third-level ones, from "Introduction" to "Representing opaque structs", with no way to see that list without scrolling, while most chapters have one or two subheadings and need no list at all. .github/workflows/main.yml pins MDBOOK_VERSION: 0.5.1, downloads that release tarball into bin/, runs mdbook test, then fetches linkcheck.sh from rust-lang/rust and runs it with --all nomicon. README.md documents mdbook build, mdbook test and the same link check.
The preprocessor is mdbook-toc, whose current release, 0.15.4, is built on mdbook-preprocessor 0.5 and so matches the mdBook 0.5 line CI pins. The agent adds a [preprocessor.toc] table to book.toml with command = "mdbook-toc", renderer = ["html"] so the preprocessor runs for the HTML build and not for mdbook test, and max-level = 3, since the book's third-level headings in ffi.md are the sub-sections readers look for and nothing in the book goes deeper. It installs the tool with cargo install mdbook-toc --locked in the sandbox and verifies the marker it will use, <!-- toc -->, which the tool replaces with a nested list of links to the headings that follow it.
Which chapters get a list is the judgement. The agent counts headings outside code blocks, so the #include lines in the C examples of ffi.md do not count, and inserts the marker directly under the first heading in chapters with four or more subheadings: ffi.md, atomics.md, other-reprs.md, exotic-sizes.md, casts.md and arc-mutex/arc-base.md. The threshold is in the pull request so a maintainer can move it. A two-heading chapter stays as it is, because a table of contents longer than the gap it saves is noise. The marker is an HTML comment, so a renderer that lacks the preprocessor, such as a reader on GitHub, sees nothing extra.
The check is the build, the tests and the links. The agent runs mdbook build and reads the generated ffi.html to confirm the list sits under the chapter title with one anchor per heading, runs mdbook test, which is unaffected because the preprocessor is restricted to the HTML renderer, and runs the same linkcheck.sh --all nomicon that CI runs, which checks every generated anchor against the headings mdBook produced. For CI it adds one step after the mdBook download that fetches the mdbook-toc-0.15.4-x86_64-unknown-linux-gnu.tar.gz release asset into the same bin/ directory, with the version in an MDBOOK_TOC_VERSION variable beside MDBOOK_VERSION, so the workflow keeps its download-a-binary shape instead of compiling the tool on every run.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add inline tables of contents to this mdBook with the mdbook-toc preprocessor. Read book.toml, src/SUMMARY.md, README.md and .github/workflows/main.yml first. Add a [preprocessor.toc] table to book.toml with command mdbook-toc, renderer restricted to html, and max-level 3. Count headings outside code blocks in every chapter and insert the <!-- toc --> marker directly under the first heading of each chapter with four or more subheadings; list the threshold and the chapters in the pull request. Install mdbook-toc with cargo install --locked, run mdbook build, read the built HTML for the longest chapter to confirm the list and its anchors, run mdbook test, and run the same linkcheck.sh command CI uses. Add a CI step after the mdbook download that fetches the mdbook-toc release binary into bin with its version in an MDBOOK_TOC_VERSION variable. Document the preprocessor in README.md. Open a pull request that quotes the build, test and link check output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 changes book.toml (one preprocessor table), .github/workflows/main.yml (one variable and one download step), README.md (an installation line beside the mdBook one) and the six chapter files that received a marker, each by a single added line. Its description lists the chapters with their subheading counts, states the threshold, and quotes the mdbook build, mdbook test and linkcheck.sh output.
A reviewer reads the list of chapters and decides whether the threshold is right for the book; moving it is a matter of adding or deleting one comment line per chapter. They confirm the CI step downloads the same version the sandbox built with, and that renderer = ["html"] keeps mdbook test on the raw Markdown. They may prefer the marker below an introductory paragraph rather than directly under the title, which is a one-line move.
Readers of the published book see, at the top of each long chapter, a nested list of its sections linking to the same anchors mdBook already generates, with the same styling as the chapter's other lists.
Run it on every pull request that adds a chapter
An automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize reads each pull request that touches src/ and counts the headings of any new or grown chapter. An automation's run is read-only, so when a chapter crosses the threshold it posts a review comment with the one line to add rather than pushing to the contributor's branch.
For an organisation with several books, a handler on the reader's own server sends this body once per repository to POST /o/{org}/sessions, naming the repository in resources and a request_id that is a UUID v5 of the repository name, so a retried call returns the run it already started. Each run reads that book's own book.toml and CI, so a book that already installs mdBook with cargo install gets a matching install step for the preprocessor, and one that pins an older mdBook gets a mdbook-toc release built for it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The work is two lines of config and a handful of comment markers, and the risk is entirely in the build: a preprocessor that is missing on the CI runner fails every build, a version built for a different mdBook line fails to parse the book, and a generated anchor that does not match mdBook's own heading ids fails the link check. The agent builds the book, runs the doctests and the link checker in its own sandbox with the exact versions CI will use, and keeps that output with the pull request.
Documentation teams keep several books, and each has its own pinned mdBook and its own CI shape. Running the same request over all of them at once, each in its own sandbox, yields one pull request per book that fits that book, with the same preprocessor and the same marker in every one.
Frequently asked questions
Why not add the marker to every chapter?
A list of two entries takes more space than it saves. The agent counts subheadings outside code blocks and marks only chapters with four or more, names the threshold in the pull request, and leaves the rest alone. Changing the threshold later is adding or removing one comment line per chapter.
Does mdbook test still pass?
Yes. The preprocessor table sets renderer = ["html"], so mdbook test runs on the chapters as written, with the marker as an ordinary HTML comment that the Markdown parser ignores.
Will the link checker accept the generated anchors?
The agent runs the same linkcheck.sh --all command CI runs against the built book, which checks every #fragment link against the ids in the generated HTML. mdbook-toc generates its anchors from the headings the way mdBook does, and the run's output is in the pull request.
What happens in CI without the preprocessor?
mdbook build fails because book.toml names a command that is not on the path. The pull request adds a download of the mdbook-toc release binary into the same bin/ directory the workflow already fills with mdBook, pinned by a version variable next to MDBOOK_VERSION.
Can the marker text be changed?
Yes. [preprocessor.toc] takes a marker key, so a book that already uses GitLab's [[_TOC_]] convention can keep it. The default <!-- toc --> is invisible in any renderer that lacks the preprocessor, which is why the agent uses it.