What the agent does
The agent reads the book's build before it reads its history, because a redirect table only helps if every build honours it. In a book like rust-lang/rust-by-example, book.toml sets git-repository-url, an edit-url-template, hash-files = true and an additional-css entry for theme/css/language-picker.css, with a [preprocessor.gettext] marked optional = true for the translations under po/; there is no [output.html.redirect] table. .github/workflows/rbe.yml pins MDBOOK_VERSION: 0.5.1, installs mdbook-i18n-helpers, runs mdbook test and mdbook build, downloads linkcheck.sh from rust-lang/rust and runs it with --all rust-by-example, then builds each language in LANGUAGES into book/<lang> with MDBOOK_BOOK__LANGUAGE set and link-checks those too. The step still carries a comment about clearing the redirects for translations, and the agent finds in git log that the MDBOOK_OUTPUT__HTML__REDIRECT='{}' override that comment described was added with the i18n support and removed again later, so today a redirect table in book.toml applies to the English build and to every translation alike, which is what makes relative targets the right choice below.
Then it asks git where pages went. git log --diff-filter=R -M --name-status -- 'src/*.md' over the full history lists the renames: src/meta/playpen.md to src/meta/playground.md, src/scope/borrow/freeze.md to src/variable_bindings/freeze.md, src/traits/disambiguating.md and supertraits.md into src/trait/, the whole src/cast/ chapter into src/types/, the src/scope/borrowing/ pages into src/scope/borrow/, three error-handling pages into src/error/multiple_error_types/ and two out of it into src/error/result/, and src/std/try.md, hashset.md and alt_key_types.md into src/std/result/ and src/std/hash/. --diff-filter=D adds the pages that were deleted outright: src/meta/test.md, replaced by the testing chapter in SUMMARY.md, and src/crates/link.md, whose material the agent finds in src/crates/using_lib.md. It also notices src/conversion/try_from_try_into.md, deleted once and present again today, which needs nothing. Each old path becomes an .html key and each target a URI relative to the redirect page, so "/meta/playpen.html" = "playground.html", "/scope/borrow/freeze.html" = "../../variable_bindings/freeze.html", "/cast/alias.html" = "../types/alias.html", and a page that moved twice, like scope/borrowing/freeze.html, points straight at its final home rather than at another redirect.
mdBook's renderer documentation says the key is the path, from the build directory, where the redirect file is created, and the value any URI the browser should go to; since 0.4.52 a key may carry a #fragment too. Relative values matter here: the same table builds the Japanese book into book/ja/ and a target like ../types/alias.html resolves inside that directory, where an absolute /rust-by-example/types/alias.html would jump out of the translation. hash-files renames stylesheets and scripts, not chapter pages, so the targets are stable. The agent writes the table in book.toml grouped by chapter with a one-line comment naming the commit that moved each page, which is what a maintainer needs when a redirect looks wrong years later.
To check it, the agent downloads the mdbook-v0.5.1-x86_64-unknown-linux-gnu release the workflow pins, since the gettext preprocessor is optional it builds without the translation helpers, and reads the generated files: book/meta/playpen.html is a small page whose refresh target is playground.html, and book/scope/borrowing/freeze.html points at the final location. It serves book/ and opens three old addresses in its own browser to watch them land, builds one translation with MDBOOK_BOOK__LANGUAGE=ja into book/ja to confirm the redirect pages appear there with the same relative targets, and runs the workflow's linkcheck.sh against both outputs so the pull request can say the checker passes with the new pages present.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add redirects for the pages this mdBook has moved or deleted. Read book.toml, src/SUMMARY.md, the theme directory and the workflow under .github/workflows first, and note which mdBook version it pins and how translations are built. Use git log with --diff-filter=R and --diff-filter=D over src/*.md on the full history to list every renamed and deleted chapter, and read the deleted pages to pick the chapter that replaced each. Add an [output.html.redirect] table to book.toml with one entry per old address, targets written relative to the redirect page so they also work inside translated builds, a page that moved twice pointing at its final location, and a comment naming the commit for each. Install the pinned mdBook release, build the English book and one translation, read the generated redirect pages, open a few old addresses in a browser, run the workflow's link check, and open a pull request with the commands and their output.",
"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 and nothing else. Its description lists every redirect as old address, new address and the commit that moved the page, quotes one generated redirect file, shows the linkcheck.sh result for the English build and for the translation it built, and names the pages it chose not to redirect and why, such as the chapter that was deleted and later restored.
A reviewer checks the targets for the deleted pages, since those are editorial choices rather than renames, and decides whether an old address should go to a section anchor instead of a chapter. After merging, the next build writes the redirect pages beside the chapters, and an old bookmark or an external link to cast/alias.html lands on the current page instead of the 404.
Run it on every mdBook in the terminal
A developer with mdbook serve running sends this body from their own machine with the book's repository in resources and reads the pull request from the console when the webhook on their API key reports the run. A team with several books sends one request per repository, each with a request_id that is a UUID v5 of the repository's full name, so a script run twice returns the runs already started rather than a second set of pull requests.
Each run reads its own history: a book that already has a redirect table gets only the entries it lacks, and a book without translations gets targets that are still relative, because that form is right in both cases.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The list of broken addresses is not in the tree; it is in the history, and only git log with the right filters says which pages moved, when, and where. The agent runs those queries, reads the deleted pages to choose targets, and proves the result with the book's own pinned mdBook release, a translated build and the workflow's link checker, all in its own sandbox with every command and its output kept in the run's record.
It also fits the table to how this book is built rather than to a generic example: relative targets because translations build into a subdirectory, no reliance on the override the workflow once set and no longer does, and a comment per entry so the next maintainer can trace it. Ten books with ten histories get ten pull requests, each with that book's own list.
Frequently asked questions
Will the redirects work in the translated books?
Yes, because the targets are relative to the redirect page and the workflow no longer clears the table for translations. A target like ../types/alias.html resolves inside book/ja/ just as it does in the English book/, and the agent builds one translation to show it.
What about pages that were deleted rather than moved?
The agent reads the deleted page's last content and the current SUMMARY.md to pick the chapter that covers the same ground, and marks those entries in the pull request as choices rather than renames. A reviewer can point one at a different chapter or at a section anchor, which mdBook has supported in redirect keys since 0.4.52.
Does hash-files break the targets?
No. mdBook's documentation says hash-files fingerprints static assets such as stylesheets and scripts and that chapter HTML files are not renamed, so playground.html stays playground.html and the redirect keeps working across builds.
Is the published site covered?
The table lives in book.toml, which every mdbook build reads, including the ones in the workflow. The pull request names the file so whoever runs the deployment can confirm their build uses the same configuration.