# Add a Typo Check to Starlight Docs

Yes. An agent runs typos over your Starlight site, excludes translations and generated files, fixes the English misspellings, adds the CI job and opens a PR.

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

## What the agent does

The agent runs the checker before it configures anything, because the first run says what the config has to exclude. In a site like tauri-apps/tauri-docs, `package.json` builds with `astro build` on Astro 7 and `@astrojs/starlight`, with `starlight-links-validator`, `starlight-llms-txt`, `starlight-blog` and a Lunaria translation tracker, and its scripts include `format:check` with Prettier and `check:translations`; `.github/workflows/check.yml` runs those two on every pull request with pnpm and Node 24 and nothing checks spelling. `locales.json` lists English plus `fr`, `es`, `zh-cn`, `ja` and `de`, and those directories sit under `src/content/docs/` beside the English ones, the Japanese and Chinese trees being the largest. `.prettierignore` already names what is generated: `src/content/docs/reference`, the per-locale `reference/cli.mdx`, `src/content/releases`, `public/release`, the `packages/releases-site` generator output and the three git submodules under `packages/`. `lunaria.config.json` carries an `ignoreKeywords` list with `typo` in it, which means a commit whose message says so does not mark the translations of the pages it touches as outdated.

A first `typos` run over the whole checkout reports hundreds of hits, nearly all of them Spanish, French and German words in the translated pages and junk in data files: `packages/releases-site/generator/data.json`, the community survey CSV in `public/`, `src/data/openCollectiveData.json`, the Korean diagrams under `public/d2/docs/ko` whose SVG text trips the checker, and `src/stale_translations`. Restricted to the English pages, the run is short and mixed: real misspellings such as `specifity`, `Februrary`, `transfered`, `occurances`, `capabilites`, `targetting`, `vistors`, `wether` and `prefered` in the blog, distribution and development pages, next to false positives, `ser` three times in `serde::ser::Serializer` inside Rust code in `develop/calling-rust.mdx` and the publisher `PACKT` in the 1.0 announcement. Outside `src/content/docs`, `astro.config.mjs` holds Spanish sidebar labels inline, `Conceptos`, `comandos`, `Versiones`, which the checker reads as English typos, and a comment in `src/content.config.ts` hyphenates `mis-slugify`.

So the config is mostly a list of what not to read. The agent writes `_typos.toml` with `files.extend-exclude` covering the five translated directories, `src/stale_translations`, `public/d2`, the releases generator, the survey CSV, `src/data` and `pnpm-lock.yaml`; `default.extend-identifiers` with `ser = "ser"` so the serde path is always valid; `default.extend-words` with `PACKT = "PACKT"`; and one `default.extend-ignore-re` pattern for the `es:` label lines in the Astro config, which keeps the English labels on the lines around them checked. Then it fixes the real misspellings in the English pages only, since the translated pages are maintained by their translators and tracked by Lunaria, and writes the word `typo` into the commit message so Lunaria does not flag every translation of those pages. The job goes into a new `typos.yml` workflow on `pull_request`, with `actions/checkout` and `crate-ci/typos` pinned to the release the agent ran, passing the config through the action's `config` input, so a contributor sees the misspelling on the pull request rather than after merge.

The proof is the run itself, three times: the whole checkout before any config, to show why the excludes exist; the English pages with the config and before the fixes, listing each real hit with its file and line; and the full checkout with the config after the fixes, which reports nothing. The agent also runs `pnpm format:check` to show Prettier is unchanged by the edits and builds the site with `astro build` so the links validator confirms no fixed word was part of a heading an anchor depended on.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a spelling check with typos to this Starlight documentation site. Read package.json, astro.config.mjs, locales.json, lunaria.config.json, .prettierignore, .gitignore and the workflows under .github/workflows first. Install the current typos release and run it over the whole checkout, then over the English pages only, and sort the hits into real misspellings, words that are valid in code or names, and files that should not be checked: translated locales, stale translations, generated references and releases, diagram SVGs, data files and the lock file. Write a _typos.toml with those excludes, identifiers and words, and an ignore pattern for the translated labels inside the Astro config. Fix the real misspellings in the English pages only and put the word typo in the commit message so the translation tracker ignores it. Add a pull_request workflow running the typos action with the config. Show the run before the config, with it before the fixes, and after, run the formatter check and the site build, and open a pull request linked to the issue with the commands and their output.",
  "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` and `.github/workflows/typos.yml`, and edits the English pages that held misspellings, with the translated trees untouched. Its description shows the three runs, the list of fixed words with file and line, the false positives and how each is allowed, and the `format:check` and `astro build` results.

A reviewer checks the allowed words, decides whether the blog's older posts should be fixed or excluded as historical, and confirms the workflow's pin. After merging, a pull request with a misspelled word in an English page fails the new check with the word, the file and the suggestion.

## Run it on every Linear issue labelled docs

An automation in the Project that holds the site takes a `linear` trigger on `linear.issue.labeled` with the label `docs`. Its runs are read-only, so the saved prompt asks for the survey: the run runs typos, sorts the hits and posts the counts and the proposed excludes as a comment on the issue, where the docs lead can say which locales and which old posts are in scope. A handler on the team's own server then starts the run that writes the pull request, sending this body with the issue's URL added to `resources` and a `request_id` that is a UUID v5 of the issue id, so a retried start returns the run already started.

A team with several Starlight sites sends one request per repository, each with its own `resources` entry; a site with one locale gets a short exclude list and a site with ten gets the long one.

## Why run it on Rush?

The checker takes a minute to add and a day to tune, because a multilingual site is mostly words it must not read: five locales, generated references, diagrams, data exports. The agent runs it in its own sandbox, reads every hit, and writes the config from what it saw rather than from a template, keeping each run's output in the run's record so the review can see why each exclude exists.

It also respects how the site is maintained: translators own the translated pages and Lunaria tracks their freshness, so the fixes stay in English and the commit message uses the keyword the tracker already ignores. Several sites get the same treatment at once, each with its own sorted list.

## Frequently asked questions

### Why not fix the typos in the translated pages too?

Most hits there are correct words in another language, and the few real ones belong to the translators who maintain those trees. The config excludes the locale directories, and the pull request lists their counts so the translation leads can decide separately.

### Will the check complain about code samples?

Identifiers inside code are where most false positives come from, like `ser` in a serde path. The agent allows each one it met through `extend-identifiers` or `extend-words`, and the pull request shows the list so a reviewer can trim it.

### Why a keyword in the commit message?

The site's Lunaria configuration lists `typo` among the keywords whose commits do not mark translations as outdated. Without it, fixing a word in an English page would flag that page's five translations as stale.

### Does it run locally too?

Yes. The same `_typos.toml` is read by the `typos` binary from the repository root, and the pull request's README note gives the one-line install so a writer can run it before pushing.

## More Starlight jobs

- [Add Versioned Docs to a Starlight Site](https://getrush.ai/run/add-versioned-docs/starlight/)
- [Run an SEO Audit on a Starlight Site](https://getrush.ai/run/seo-audit/starlight/)
- [Add a Blog to a Starlight Docs Site](https://getrush.ai/run/add-blog/starlight/)

## The same job on other stacks

- [Add a Typo Check to a VitePress Site in CI](https://getrush.ai/run/add-typo-check/vitepress/)
- [Add a Typo Check to a Zola Site](https://getrush.ai/run/add-typo-check/zola/)
- [Add a Typo Check to a Docusaurus Site in CI](https://getrush.ai/run/add-typo-check/docusaurus/)

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