# Add Admonitions to an mdBook

Yes. An agent installs the mdbook-admonish preprocessor in your book, turns the bold-NOTE blockquotes into styled callouts, keeps CI building, and opens a PR.

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

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

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

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

## More mdBook jobs

- [Add a GitHub Pages Deploy Workflow to an mdBook](https://getrush.ai/run/add-deploy-workflow/mdbook/)
- [Build an mdBook on Every Pull Request Before It Deploys](https://getrush.ai/run/add-docs-build-check/mdbook/)
- [Add Giscus Comments to an mdBook](https://getrush.ai/run/add-giscus-comments/mdbook/)

## More jobs like this: Hand off a long task

- [Add Analytics to an Astro Blog](https://getrush.ai/run/add-analytics/astro/)
- [Add Google Analytics to a Gatsby Blog](https://getrush.ai/run/add-analytics/gatsby/)
- [Add ansible-lint to CI for an Ansible Role](https://getrush.ai/run/add-ansible-lint/ansible/)

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