# Add a Typo Check to a VitePress Site in CI

Yes. An agent adds the typos checker to your VitePress docs, fixes the Markdown prose, keeps API names and code examples intact, adds a CI workflow, and opens a PR.

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

## What the agent does

The agent reads the site's layout and tooling first. In a site laid out like vuejs/docs, `package.json` runs `vitepress build` with `vitepress ^2.0.0-alpha.17` and the `@vue/theme` package, pins `packageManager` to `pnpm@10.33.0`, requires Node 20 or newer in `engines`, and has a `preinstall` script that refuses any package manager but pnpm. The content is 119 Markdown files under `src/`, with `guide/` (52 files), `api/` (29), `tutorial/` (16), `about/` (6) and `style-guide/` (5) carrying most of the prose; `.vitepress/config.ts` builds the sidebar, registers `vitepress-plugin-llms` and the group-icons plugin, and sets Open Graph tags and a sitemap. Formatting is Prettier with `.prettierrc` (no semicolons, single quotes, `printWidth` 75) and `.editorconfig`, `.prettierignore` skips `*.vue`, and `.github/workflows/` holds one file, `automerge.yml`, which merges Dependabot's theme bumps; nothing checks spelling, and `netlify.toml` builds with `pnpm run build` on Node 24.

The configuration is `_typos.toml` at the root. `files.extend-exclude` lists `pnpm-lock.yaml` and `src/public/`, and the `.vitepress/dist` and `.vitepress/cache` directories are already covered by `.gitignore`, which typos honours. The pages are dense with Vue API names that a dictionary does not know, such as `defineProps`, `onMounted`, `watchEffect`, `toRefs` and `shallowRef`, and with the `:::tip` and `:::warning` container syntax and `<script setup>` blocks that VitePress allows inside Markdown, so the agent runs `typos` once with no allow list, reads the report, and puts every API name it flags under `default.extend-identifiers` with a comment naming the page, rather than silencing whole files. The `src/translations/` page lists the names of community translation sites and goes under `extend-words` for the same reason.

The corrections are then made in place. Prose under `src/guide/`, `src/tutorial/` and `src/about/` is edited directly; a comment inside a fenced code block is corrected; a word that is also an identifier is left alone and recorded. A page such as `guide/essentials/reactivity-fundamentals.md` carries dozens of fenced blocks, so after each batch of edits the agent runs `pnpm run build` to be sure a changed character inside a `<script setup>` block or a container marker still compiles, and `pnpm exec prettier --check src` so the result matches the style the repository already enforces.

The CI job is a new `.github/workflows/typos.yml`, since `automerge.yml` is specific to Dependabot and should not grow a second job. It runs on `pull_request` and on pushes to `main`, with `permissions: contents: read`, one checkout step and `crate-ci/typos` pinned to a release tag on `ubuntu-latest`; it needs neither Node nor pnpm, so it reports in seconds. The agent runs `actionlint` over the workflow, `pnpm run build` one last time, and `typos` until it exits clean 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 VitePress site. Read package.json, .vitepress/config.ts, .prettierrc, .prettierignore, .editorconfig, netlify.toml, .gitignore and the layout of src/ and .github/ first. Install typos-cli with cargo install --locked and write _typos.toml at the root with files.extend-exclude for pnpm-lock.yaml and src/public/. Run typos from the root with no allow list, then put every framework API name it flags under default.extend-identifiers with a comment naming the page, and the translation site names under default.extend-words. Fix real misspellings in the Markdown prose and in comments inside code blocks; never change an identifier inside a code block. Run pnpm install, pnpm run build and pnpm exec prettier --check src after the edits. Add .github/workflows/typos.yml running crate-ci/typos pinned to a release tag on pull_request and on pushes to main with contents: read permissions; do not touch automerge.yml. Run actionlint and typos until everything exits clean, then open a pull request listing every correction as a before-and-after pair grouped by section under src/ 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` and `.github/workflows/typos.yml`, and changes the Markdown files under `src/` where a word was corrected. Its description lists the corrections as before-and-after pairs grouped by section (`guide`, `api`, `tutorial` and so on), the allow-list entries with the page that justifies each, the `pnpm run build` summary and the Prettier check after the edits, and the final `typos` exit status.

The new workflow runs on the pull request itself, so its first green check is visible next to the Netlify deploy preview before anyone merges. Because `.vitepress/config.ts` is TypeScript and in scope, the description also says whether any of its `nav` or `sidebar` labels changed, since those strings appear on every page.

Before merging, a reviewer reads the pairs for a spelling that was intentional in a quoted error message or a code comment, checks that no identifier was changed inside a fenced block, and decides whether translation teams that mirror this repository should be told which English paragraphs moved.

## Run it on every documentation pull request

A team with several VitePress sites sends this body once per repository from its own server, each `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 site: one whose docs live beside the package source in a `docs/` directory gets `_typos.toml` scoped to that directory, and one that already has a `ci.yml` gets the job added there.

Once the job exists, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if the typos job failed on this pull request, read its log and comment with the corrections it suggests, file by file, without pushing" starts one run per push to an open pull request. The trigger adds the pull request after the prompt and fills in nothing else, and only work by an owner, member or collaborator fires it, so a contributor's pull request keeps its red check until a maintainer reads the comment.

## Why run it on Rush?

A framework's documentation is the hardest kind of text to spell-check: every page mixes prose with the names of the framework's own functions, and the first run of a checker reports hundreds of them. Sorting those into real misspellings and identifiers is a long, careful afternoon by hand. The agent does it in the open, writing a comment beside each allow-list entry and running the site's own build and formatter after every batch of edits, so a fix never breaks a page.

The report, the build output, the Prettier check and the final clean exit stay with the run, so a reviewer sees the decision behind each entry rather than a mute allow list. A team that owns docs sites for several packages runs the same request across all of them at once, each in its own sandbox.

## Frequently asked questions

### Will it touch the Vue code inside the Markdown?

Only comments. VitePress pages may hold `<script setup>` blocks, fenced examples and container markers, and a word there that is a component or function name is never changed; it goes under `default.extend-identifiers` with a comment naming the page. The agent runs `pnpm run build` after each batch of edits so a change inside a block that breaks compilation is caught in the sandbox.

### Why a new workflow file instead of a job in the existing one?

The only existing workflow is `automerge.yml`, which runs on every pull request but does its work only when the actor is Dependabot. A typo job belongs to a file of its own, where its trigger and permissions are easy to read and a reviewer does not have to reason about the Dependabot condition.

### Does it need pnpm to run in CI?

No. The typos action is a single binary over the checked-out files, so the workflow has no Node setup and no `pnpm install`, and it reports in seconds. The agent uses pnpm only in its sandbox, to run the build and the Prettier check after its edits, the same way `netlify.toml` builds the site.

### What happens to translations that mirror this repository?

Nothing in the run, because translations live in their own repositories. The pull request's description groups corrections by section so a translation maintainer can see which English paragraphs changed and update their copy when they next sync.

## More VitePress jobs

- [Add Versioned Docs to a VitePress Site](https://getrush.ai/run/add-versioned-docs/vitepress/)
- [Add Author Pages to a VitePress Blog](https://getrush.ai/run/add-author-pages/vitepress/)
- [Add a Dark Mode Toggle to a VitePress Blog With a Custom Theme](https://getrush.ai/run/add-dark-mode/vitepress/)

## The same job on other stacks

- [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/)
- [Add a Typo Check to an Eleventy Blog in CI](https://getrush.ai/run/add-typo-check/eleventy/)

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