What the agent does
The agent reads the book's build first. In a book like rust-lang/async-book, book.toml has a [book] section, create-missing = false under [build], an [output.html] with git-repository-url and a site-url of /async-book/, and an [output.linkcheck2] renderer; there is no preprocessor and no additional-js. src/SUMMARY.md lays out a guide part, a reference part and the old chapters, and src/part-reference/structured.md carries a literal TODO diagram line right after the paragraph that describes tasks as a tree with parents outliving their children. .github/workflows/ci.yml installs mdbook and mdbook-linkcheck2 with taiki-e/install-action pinned by commit, runs mdbook build, tests the examples/ crates, and deploys book/html to GitHub Pages on master; ci/spellcheck.sh runs aspell over the Markdown with ci/dictionary.txt as the allow list and, by its own comment, does not skip code blocks. .gitignore ignores /book/.
Wiring the preprocessor is the mechanical part. The agent installs mdbook-mermaid with cargo install, runs mdbook-mermaid install . from the book root, and commits what that command changes: a [preprocessor.mermaid] section with command = "mdbook-mermaid" in book.toml, additional-js = ["mermaid.min.js", "mermaid-init.js"] under [output.html], and the two JavaScript files it copies beside book.toml. mermaid-init.js is where the theme is set, and the agent switches it to follow the book's light and dark themes rather than a fixed one. In ci.yml it adds an install step for mdbook-mermaid with the same taiki-e/install-action commit and fallback: cargo-install, as the linkcheck step already does, so mdbook build on CI sees the preprocessor.
Then the diagrams, which is the part worth reading. The TODO diagram line in structured.md becomes a mermaid code block drawing the task tree the paragraph describes: a root task with two children, one of them with a child of its own, with the parent-outlives-child rule and cancellation flowing down as labelled edges. src/part-guide/concurrency.md explains time-slicing of threads on one core in prose, and gets a Gantt-style block showing two threads interleaved across one core beside a block showing them in parallel on two. Each diagram keeps the chapter's own vocabulary (task, parent, child, core) so the text and the picture agree, and each is placed after the sentence it illustrates with a one-line caption.
The agent builds and looks. mdbook build must succeed with create-missing = false, the rendered book/html/part-reference/structured.html must contain the mermaid block, and the agent opens it in the browser in its sandbox to see the diagram drawn rather than a code block. Because the spellcheck reads code blocks, node labels are real words or are added to ci/dictionary.txt, and ci/spellcheck.sh list must exit clean. It runs the linkcheck renderer too, since mdbook build now runs both renderers, before opening the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Mermaid diagrams to this mdBook. Read book.toml, src/SUMMARY.md, src/part-reference/structured.md, src/part-guide/concurrency.md, .github/workflows/ci.yml, ci/spellcheck.sh, ci/dictionary.txt and .gitignore first. Install mdbook-mermaid, run mdbook-mermaid install . and commit the book.toml changes and the two JavaScript files it adds; set mermaid-init.js to follow the book's theme. Replace the TODO diagram line in src/part-reference/structured.md with a mermaid block drawing the task tree described in the surrounding paragraph, with cancellation shown flowing from parent to child, and add a mermaid block to src/part-guide/concurrency.md showing two threads time-sliced on one core and running in parallel on two. Add an mdbook-mermaid install step to .github/workflows/ci.yml using the same taiki-e/install-action commit as the other tools with fallback cargo-install. Run mdbook build, open the rendered structured chapter in the browser to confirm the diagram renders, run ci/spellcheck.sh list and add any new words to ci/dictionary.txt, then open a pull request with a screenshot of each diagram.",
"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, .github/workflows/ci.yml, src/part-reference/structured.md, src/part-guide/concurrency.md and ci/dictionary.txt, and adds mermaid.min.js and mermaid-init.js at the book root. Its description shows a screenshot of each rendered diagram from the sandbox browser, the mdbook build output with the preprocessor listed, and the spellcheck result.
It explains the two choices a maintainer will ask about: the JavaScript files are committed rather than fetched at build time, which is how mdbook-mermaid install works and keeps the Pages deploy free of network calls, and the Mermaid source lives in the Markdown so a chapter can be edited without a drawing tool. It also notes that mermaid.min.js does not update itself; rerunning the install command refreshes it.
Before merging, a reviewer reads each diagram against its paragraph for accuracy, which no build can check, and decides whether the older chapters that describe executors and wakers deserve the same treatment in a follow-up.
Run it on every Linear issue labelled diagram
An automation on the Project with a linear trigger on linear.issue.labeled, diagram in config.labels, and the prompt 'this issue names a chapter whose text describes a structure or a sequence in prose; add a mermaid block that draws it, using the chapter's own terms, build the book, check the spellcheck, and open a pull request with a screenshot' starts one run per labelled issue once the preprocessor is in place. The trigger adds the issue after the prompt and fills in nothing else, so an issue about the executor chapter and one about the streams chapter each get a run that reads that file.
A team that maintains several mdBooks sends this body once per repository from its own server, each POST /o/{org}/sessions with that repository in resources and 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 has additional-js entries gets the two files appended, and one that builds with a different CI tool gets the install step in that tool's syntax.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The preprocessor setup is five minutes; the diagrams are the work, and they only help if they match the prose. The agent reads the chapter before it draws, uses the chapter's vocabulary, and checks the rendered page in a real browser in its sandbox, which catches the blank box a wrong theme or an unloaded script leaves behind. It also knows the book's own checks, so the spellcheck that reads code blocks does not fail on a node label.
The build log, the screenshots and the diff stay with the run, so a reviewer judges the diagrams themselves rather than whether the tooling works. A team with several books runs the same request across all of them at once.
Frequently asked questions
Does GitHub Pages need anything else?
No. The workflow already uploads book/html, and the two JavaScript files are part of that output once additional-js names them. The only CI change is installing mdbook-mermaid before mdbook build, which the pull request adds with the same pinned action the other tools use.
Do the diagrams follow the book's dark theme?
They can. mermaid-init.js is the configuration file the install command copies, and the pull request sets its theme from the current mdBook theme instead of a fixed value, so a reader on the dark theme gets a dark diagram.
Will the link checker or spellcheck complain?
The linkcheck renderer ignores code blocks, so Mermaid source does not affect it. The spellcheck script reads code blocks, by its own comment, so the agent uses real words for node labels and adds anything else to ci/dictionary.txt, and runs ci/spellcheck.sh list to prove it is clean.
Could the diagrams be images instead?
Yes, by rendering the same source to SVG with the Mermaid CLI and committing the files, which removes the runtime JavaScript. The pull request keeps the source in Markdown so the next edit needs no tool, and names the CLI route for a book that must ship without scripts.
More mdBook jobs
The same job on other stacks
- Add Mermaid Diagrams to a MkDocs Site (MkDocs)
- Add Mermaid Diagrams to Sphinx Docs (Sphinx)
- Add Mermaid Diagrams to a Starlight Docs Site (Starlight)