# Add Mermaid Diagrams to an mdBook

Yes. An agent wires mdbook-mermaid into your book, draws the diagrams the text asks for as mermaid blocks, updates CI and the spellcheck, and opens a PR.

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

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

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

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

- [Add Open Graph Tags to an mdBook Site](https://getrush.ai/run/add-open-graph-tags/mdbook/)
- [Add PDF Export to an mdBook Book](https://getrush.ai/run/add-pdf-export/mdbook/)
- [Add Redirects for Moved Pages to an mdBook](https://getrush.ai/run/add-redirects/mdbook/)

## The same job on other stacks

- [Add Mermaid Diagrams to a MkDocs Site](https://getrush.ai/run/add-mermaid-diagrams/mkdocs/)
- [Add Mermaid Diagrams to Sphinx Docs](https://getrush.ai/run/add-mermaid-diagrams/sphinx/)
- [Add Mermaid Diagrams to a Starlight Docs Site](https://getrush.ai/run/add-mermaid-diagrams/starlight/)

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