# Add a Typo Check to an mdBook in CI

Yes. An agent adds the typos checker to your mdBook with a config that skips translations, fixes what it finds, adds a CI job, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-typo-check/mdbook/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the book is built and what is already in CI. In a book laid out like rust-lang/rust-by-example, `book.toml` names the book, turns on an editable playground, boolean-and search, a `git-repository-url` and `edit-url-template` pointing at the source on GitHub, an optional `gettext` preprocessor and `po` as an extra watch directory; the chapters are Markdown files under `src/` listed in `src/SUMMARY.md`, and `po/` holds `es`, `ja`, `ko` and `zh` translations as gettext files whose `msgid` lines repeat every English paragraph. `.github/workflows/rbe.yml` is one job: it installs nightly Rust with `rust-docs`, downloads mdBook 0.5.1 from its release tarball, installs `mdbook-i18n-helpers` 0.4.0 with `cargo install`, runs `mdbook test` and `mdbook build`, checks links with the `linkcheck.sh` script from the Rust repository, builds each translation with `MDBOOK_BOOK__LANGUAGE`, and uploads the result. Nothing checks spelling, `.gitattributes` forces LF line endings, and `TRANSLATING.md` describes how translators refresh the `po` files from the English source.

The configuration is `typos.toml` at the root. Its `[files]` section excludes `po/`, because every English string appears there a second time as a `msgid` and the translators regenerate those files from `src/`, and `theme/`, which holds a handlebars head and a stylesheet rather than prose. Its `[default.extend-words]` and `[default.extend-identifiers]` tables take the identifiers and deliberate spellings the first run flags, each with a comment saying which chapter uses it and why it stays, so the file reads as a list of decisions rather than a mute allow list. The agent installs `typos-cli` with `cargo install --locked` and runs `typos` from the root, then works through the report in two piles.

Prose corrections are made in place. A misspelling inside a fenced Rust block gets more care, because `mdbook test` compiles those blocks: a typo in a comment is safe to fix, a typo that is also an identifier is left alone and recorded in `extend-identifiers` with a note, and after every change inside a code block the agent reruns `mdbook test` with the same 0.5.1 binary CI uses. The pull request lists every correction as a before-and-after pair grouped by chapter, so a reviewer can scan them in a minute.

The CI step is a second job in `rbe.yml` named `typos`, running `crate-ci/typos` pinned to a release tag on `ubuntu-latest` with nothing else installed, so it reports in seconds and independently of the slow test job. The agent runs `mdbook build` and `actionlint` over the edited workflow in its sandbox, and `typos` once more to confirm a clean exit before opening the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a typo check to this mdBook. Read book.toml, src/SUMMARY.md, .github/workflows/rbe.yml, TRANSLATING.md and the layout of po/ and theme/ first. Install typos-cli with cargo install --locked and write typos.toml at the root with files.extend-exclude for po/ and theme/, then run typos from the root. Fix real misspellings in the Markdown prose and in comments inside code blocks; never change an identifier inside a code block, record it under extend-identifiers with a comment naming the chapter instead, and put deliberate spellings under extend-words with a comment. Rerun mdbook test with the same mdBook version the workflow pins after any change inside a code block. Add a separate typos job to rbe.yml using crate-ci/typos pinned to a release tag. Run mdbook build, actionlint and typos until it exits clean, and open a pull request that lists every correction as a before-and-after pair grouped by chapter and every allow-list entry with its reason.",
  "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 adds `typos.toml`, adds the `typos` job to `.github/workflows/rbe.yml`, and changes the Markdown files under `src/` where a word was corrected. Its description lists the corrections as pairs grouped by chapter, the allow-list entries with their reasons, the `mdbook test` and `mdbook build` summaries after the edits, and the final `typos` exit.

Every correction to the English source changes a `msgid` the four translations key on, so those entries go stale until translators run the `mdbook-i18n-helpers` refresh described in `TRANSLATING.md`; the description names the affected chapters so the translation maintainers know what to expect.

Before merging, a reviewer reads the pairs for any spelling that was intentional in context, decides whether the job should also run on a schedule so new dictionary releases surface older typos, and whether `po/` should be checked after all once the translators have refreshed it.

## Run it on every pull request

A team that maintains several books sends this body once per repository from its own server, each a `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 workflow: a book that already pins the actions by commit SHA gets the typos step pinned the same way, and one with no translations gets a config without the `po/` exclusion.

Once the job exists, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if the typos job failed on this pull request, read the job output and comment with the corrections it suggests, file by file" starts one run per pull request; its runs read the repository and comment, but do not push. The trigger adds the pull request after the prompt, and only work by an owner, member or collaborator fires it.

## Why run it on Rush?

The first run of a spell checker over a large book is the expensive part: hundreds of chapters, examples whose identifiers look like typos, and translations that repeat every finding. Doing it by hand means a long afternoon of judgement calls; the agent makes each one in the open, with a comment in `typos.toml` and a line in the pull request, and reruns `mdbook test` so a fix inside an example never breaks the build.

The checker's output, the test runs and the final clean exit stay with the run, so a reviewer sees the decision behind each allow-list entry. A team with many books runs the same request across all of them at once, each in its own sandbox.

## Frequently asked questions

### Why exclude the translations?

The gettext files in `po/` repeat every English paragraph as a `msgid`, so each typo in `src/` would be reported twice, and the translators regenerate those files from the English source as `TRANSLATING.md` describes. Checking `src/` catches the typo at its origin; the description notes that `po/` can be added back once the translations have been refreshed.

### Will fixing a word inside a code block break mdbook test?

It can, which is why the agent only edits comments inside blocks, never identifiers, and reruns `mdbook test` with the pinned mdBook after each such edit. An identifier that reads as a typo goes under `extend-identifiers` with a comment naming the chapter.

### Why a separate job rather than a step in the existing one?

The existing job installs nightly Rust, mdBook and the i18n helpers before it runs anything, while the typos action needs none of that. A job of its own reports within seconds of a push, and a spelling failure does not hide behind a build failure or the other way round.

### What happens to the translations after the corrections?

Each changed English paragraph is a changed `msgid`, so the matching entries in the four `po` files are stale until the translators run the refresh in `TRANSLATING.md`. The pull request lists the chapters touched so the translation maintainers can plan that pass.

## More mdBook jobs

- [Add Admonitions to an mdBook](https://getrush.ai/run/add-admonitions/mdbook/)
- [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/)

## The same job on other stacks

- [Add a Spell Check to MkDocs Docs in CI](https://getrush.ai/run/add-typo-check/mkdocs/)
- [Add a Typo Check to a Pelican Site](https://getrush.ai/run/add-typo-check/pelican/)
- [Add a Typo Check to a Sphinx Documentation Site](https://getrush.ai/run/add-typo-check/sphinx/)

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