What the agent does
The agent reads the book before it touches a chapter. In a book laid out like rust-embedded/book, book.toml is eleven lines: [book] with authors, src = "src" and title = "The Embedded Rust Book", and [output.html] with only git-repository-url. There is no [preprocessor.*] table and no additional-css, so the HTML renderer runs with its defaults. src/SUMMARY.md nests chapters under Introduction, Getting started, Peripherals and the rest, and .gitignore excludes book, the build directory. .github/workflows/ci.yml installs mdbook with actions-rs/install at latest, copies the binary into ~/cargo-bin behind an actions/cache keyed cache-cargo, then runs mdbook build, mdbook test and linkchecker book, and on a push to master publishes book/ with peaceiris/actions-gh-pages. The callouts today are blockquotes: > **NOTE** and > **NOTE**: paragraphs in src/start/exceptions.md, start/hardware.md, start/qemu.md, start/panicking.md, peripherals/singletons.md, intro/install/verify.md, intro/install/linux.md, intro/install/macos.md and portability/index.md, rendered as plain indented quotes with no colour or icon.
The preprocessor is mdbook-admonish, installed with cargo install mdbook-admonish --locked. Its own mdbook-admonish install . command writes two things into book.toml: a [preprocessor.admonish] table with command = "mdbook-admonish", and additional-css = ["./mdbook-admonish.css"] under [output.html], and it copies mdbook-admonish.css into the book root, which the agent commits because the renderer reads it at build time. The agent runs that command rather than editing the table by hand so the recorded asset version matches the CSS file, and it adds after = ["links"] to the table so the {{#include}} directives in the book are expanded before the admonitions are parsed. A callout is then a fenced block whose info string is admonish note, with warning, tip, info, danger and example as the other types the book is likely to want.
Conversion is where judgement goes. The agent rewrites each > **NOTE** blockquote as a admonish note fence and each one that warns about a wrong board revision, a stale memory.x after a target change, or a program that will not crash under QEMU as admonish warning, keeping the text verbatim. A blockquote that quotes something, such as the one-line description at the top of README.md, stays a blockquote. Inline code, links and the reference-style link definitions inside the notes are kept as they are, since the fence body is ordinary Markdown. The agent does not touch SUMMARY.md and adds no new chapter; the only Markdown it changes is the nine files with notes.
The check is the build. In the sandbox the agent installs mdbook and the preprocessor, runs mdbook build and confirms the output for a converted page contains an element with the admonition class and that book/mdbook-admonish.css was copied, then runs mdbook test and linkchecker book the way CI does. For CI itself it adds one step before Build book: cargo install mdbook-admonish --locked when the cache missed, with the binary copied into the same ~/cargo-bin directory the workflow already caches, so a cache hit skips both installs. Without that step mdbook build fails in CI with the preprocessor command not found, which is the failure the agent reproduces first and fixes second.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add admonitions to this mdBook with the mdbook-admonish preprocessor. Read book.toml, src/SUMMARY.md, README.md, .gitignore and .github/workflows/ci.yml first, then find every blockquote that starts with a bold NOTE across src/. Install mdbook-admonish with cargo install --locked and run mdbook-admonish install . so it writes the preprocessor table and the additional-css entry into book.toml and copies mdbook-admonish.css; commit the CSS. Add after = [\"links\"] to the preprocessor table. Convert the NOTE blockquotes into admonish note fences, using admonish warning for the ones that warn about wrong hardware revisions, stale memory.x files or programs that behave differently under QEMU; leave quotation blockquotes alone and keep every note's text, links and inline code unchanged. Add a CI step that installs mdbook-admonish into the cached ~/cargo-bin directory before mdbook build. Run mdbook build, mdbook test and linkchecker book, confirm the built HTML contains admonition elements, then open a pull request that quotes the output and lists each converted file.",
"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 (the preprocessor table and additional-css), adds mdbook-admonish.css at the book root, changes .github/workflows/ci.yml (one install step) and the nine chapter files that held notes, and nothing else. Its description quotes the mdbook build, mdbook test and linkchecker output, lists each converted file with the count of notes and warnings in it, and includes one before-and-after pair so the reviewer sees the fence syntax next to the blockquote it replaced.
A reviewer checks that the text inside each callout is byte-for-byte what the blockquote said, which is why the agent lists the files rather than summarising them, and that nothing that was a quotation became a note. They confirm the CSS file is committed, since a book.toml that references a missing stylesheet renders unstyled callouts, and that the CI step runs before the build and lands in the cached directory. They may want a different type for a particular note, which is a one-word change on the fence.
Readers of the published book see the same words with a coloured left border, an icon and a title, and the GitHub Pages deploy does not change because it still publishes book/.
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 runs on each pull request that touches src/ and reads the diff for a new > **NOTE** blockquote. An automation's run is read-only, so it posts a review comment with the fence form of that note rather than pushing to the contributor's branch, and the contributor applies it.
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 finds that book's own callout convention, which may be > **Note**, > **Warning** or an HTML <div>, and converts the one it finds.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A documentation change like this one is wide and shallow: nine files, dozens of notes, and a build that fails if the preprocessor is not on the path. The agent installs the tool, runs the build, the doctests and the link checker in its own sandbox exactly as CI does, and keeps the output with the pull request, so the reviewer's job is reading prose, not running cargo.
Books accumulate conventions one contributor at a time. Running the same conversion over several books at once, each in its own sandbox, gives each one a pull request that matches its own notes and its own CI, with the same tool and the same fence syntax across all of them.
Frequently asked questions
Why run mdbook-admonish install instead of editing book.toml?
Because the install command writes the preprocessor table, the additional-css entry and the CSS file together, and records the asset version it shipped, so a later upgrade can tell when the stylesheet is stale. Editing the table by hand and forgetting the CSS gives unstyled callouts with no error.
Will mdbook test and the link checker still pass?
The agent runs both after the conversion. Admonition fences are not Rust code blocks, so mdbook test ignores them, and the links inside the notes are unchanged, so linkchecker sees the same targets it did before.
What happens in CI without the preprocessor?
mdbook build fails because the [preprocessor.admonish] table names a command that is not installed. The pull request adds a cargo install mdbook-admonish --locked step that lands in the same ~/cargo-bin directory the workflow already caches, so the cost is paid once per cache key.
Which blockquotes are converted?
Only the ones that begin with a bold NOTE marker, which is the book's own convention for callouts. A blockquote that quotes text stays a blockquote. The pull request lists every file it changed so the split is reviewable.
Can the callout types be changed later?
Yes. The type is the word after admonish on the fence line; note, warning, tip, info, danger and example are available, and a title can be added after the type. The CSS covers all of them.