# Add a Table of Contents to mdBook Chapters

Yes. An agent installs the mdbook-toc preprocessor, adds an inline table of contents to your long chapters, keeps mdbook test and linkcheck passing, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-table-of-contents/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 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`

```json
{
  "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"
    }
  ]
}
```

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

## 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.

## More mdBook jobs

- [Add a Typo Check to an mdBook in CI](https://getrush.ai/run/add-typo-check/mdbook/)
- [Add Admonitions to an mdBook](https://getrush.ai/run/add-admonitions/mdbook/)
- [Add a GitHub Pages Deploy Workflow to an mdBook](https://getrush.ai/run/add-deploy-workflow/mdbook/)

## The same job on other stacks

- [Add a Table of Contents to Zola Posts](https://getrush.ai/run/add-table-of-contents/zola/)
- [Add a Table of Contents to an Astro Blog](https://getrush.ai/run/add-table-of-contents/astro/)
- [Add a Table of Contents to Eleventy Blog Posts](https://getrush.ai/run/add-table-of-contents/eleventy/)

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