# Add a Spell Check to MkDocs Docs in CI

Yes. An agent adds codespell to your MkDocs project with a pinned version and an allow list, fixes the misspellings in docs and docstrings, and wires it into CI.

[Run this on Rush](https://cloud.getrush.ai/run/add-typo-check/mkdocs/). 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 docs are built and checked. In a project laid out like encode/httpx, `mkdocs.yml` uses the Material theme with a `custom_dir` of `docs/overrides`, a `nav` of about twenty pages under `docs/` including an `advanced/` folder, and the `mkautodoc` extension, which pulls the API reference on `docs/api.md` straight from the docstrings in the `httpx` package, so a typo in a docstring is a typo on the site. `requirements.txt` pins the tooling, with a comment explaining that tools are pinned and package dependencies are not: `mkdocs==1.6.1`, `mkdocs-material==9.6.18`, `mkautodoc==0.2.0`, `ruff==0.12.11` and `mypy==1.17.1`. CI in `.github/workflows/test-suite.yml` runs on Python 3.9 through 3.13 and calls the shell scripts in order: `scripts/install`, `scripts/check`, which runs `sync-version`, `ruff format --diff`, `mypy` and `ruff check` over `httpx tests`, then `scripts/build`, which runs `python -m build`, `twine check` and `mkdocs build`, then `scripts/test` and `scripts/coverage`. Nothing checks spelling anywhere.

The agent adds `codespell` to `requirements.txt` beside the other pinned tools, at the version it installs, and a `[tool.codespell]` table in `pyproject.toml` next to the existing `[tool.ruff.lint]` sections. The table skips `docs/img`, `docs/css`, `CHANGELOG.md`, the lockfile-like generated files and `.git`, and lists the paths to check as `docs httpx tests README.md`. It runs `codespell` once from the root and sorts the report into real misspellings, which it fixes in place, and identifiers or deliberate spellings, which go into `ignore-words-list` with a short comment each, so the table reads as a set of decisions.

Fixes inside docstrings change files under `httpx/`, so after each such edit the agent reruns `scripts/check` to be sure `ruff format --diff` and `mypy` are still clean, and it reruns `mkdocs build` so a corrected word in a Markdown file that `mkautodoc` or an admonition relies on still renders. Prose fixes in `docs/*.md` are listed in the pull request as before-and-after pairs grouped by page.

The CI change is one line in `scripts/check`: `codespell` with no arguments, since the configuration carries the paths. Because `test-suite.yml` already calls that script on every push and pull request across the Python matrix, no workflow file changes. The agent runs `scripts/check` and `scripts/build` end to end in its sandbox and confirms 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 spell check to this MkDocs project. Read mkdocs.yml, requirements.txt, pyproject.toml, every script under scripts/ and every file under .github/workflows first. Add codespell to requirements.txt pinned like the other tools, and a [tool.codespell] table in pyproject.toml that skips images, stylesheets, the changelog and generated files and checks the docs directory, the package, the tests and the README. Run codespell from the root. Fix real misspellings in Markdown prose and in docstrings, rerunning the existing check script after any change under the package and mkdocs build after any docs change; put identifiers and deliberate spellings in ignore-words-list with a comment each. Add a codespell line to the check script that CI already runs rather than a new workflow. Run the check and build scripts end to end, then open a pull request that lists every correction as a before-and-after pair grouped by page and every ignore 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 the pinned `codespell` line to `requirements.txt`, the `[tool.codespell]` table to `pyproject.toml`, one line to `scripts/check`, and the corrected words in files under `docs/` and in docstrings under the package. Its description lists the corrections as pairs grouped by page, the ignore entries with their reasons, and the output of `scripts/check` and `scripts/build` from the sandbox.

After the merge, every push and pull request runs the spell check inside the existing lint step on every Python version in the matrix, and a new misspelling fails `scripts/check` before the tests start, in the same place a ruff or mypy error would.

Before merging, a reviewer reads the pairs for any spelling that was intentional in context, such as a quoted error message, checks that no docstring change altered a signature line that `mkautodoc` renders, and decides whether the changelog should be checked after all.

## Run it on every new documentation site

A team that maintains several Python projects with MkDocs sites 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 layout: a project whose CI calls `pre-commit` gets the codespell hook instead of a script line, and one with docs in another language gets that language's dictionary left out.

Once the check exists, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if the lint step failed on this pull request because of codespell, read its output and comment with the corrections, file by file" starts one run per pull request. 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 pass of a spell checker over a documented library is mostly judgement: which words are identifiers, which are quoted output, which are real. The agent makes each call in the open, with a comment in the config and a pair in the pull request, and reruns the project's own check and build scripts after every change inside the package so a docstring fix never breaks a type check.

The checker's output, the check script runs and the final build stay with the run, so a reviewer can see what was flagged and what was fixed. A team with many projects starts one run per repository at once, each in its own sandbox with its own virtualenv.

## Frequently asked questions

### Why codespell rather than another checker?

The project pins its tooling in `requirements.txt` and runs it through shell scripts, and codespell is a Python package that fits both, with its configuration in `pyproject.toml` next to ruff. It also understands code, so identifiers in docstrings produce fewer false hits than a prose checker would.

### Will fixing a docstring break anything?

It can touch a line `mkautodoc` renders, so the agent reruns the check script, which includes `ruff format --diff` and `mypy`, and `mkdocs build` after any change under the package. A fix that changes a signature line is reverted and listed as a question for the reviewer.

### Why no new workflow file?

The existing `test-suite.yml` already runs `scripts/check` on every push and pull request. One line in that script adds the check across the whole Python matrix, with nothing new to maintain in `.github/workflows/`.

### What goes in the ignore list?

Identifiers that read as typos, deliberate spellings in quoted output and names, each with a comment saying which page or module uses it. The pull request lists them so a reviewer can object to any before merge.

## More MkDocs jobs

- [Add Versioned Documentation to an MkDocs Site With mike](https://getrush.ai/run/add-versioned-docs/mkdocs/)
- [Migrate MkDocs API Docs From mkautodoc to mkdocstrings](https://getrush.ai/run/migrate-to-mkdocstrings/mkdocs/)
- [Add a Workflow That Deploys MkDocs Documentation on Every Push](https://getrush.ai/run/add-deploy-workflow/mkdocs/)

## The same job on other stacks

- [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/)
- [Add a Typo Check to Starlight Docs](https://getrush.ai/run/add-typo-check/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/)
