All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading