# Add a Typo Check to a Zola Site

Yes. An agent runs typos on a Zola theme, fixes the real misspellings, writes a config that ignores the Latin filler, adds the check to CI, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-typo-check/zola/). 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 writing any config, because the right ignore list comes from the findings. In a theme like getzola/even, `typos` 1.52.0 reports 15 findings on the checkout: `varius` eight times, `Nam` three times and `facilisi` once, all inside the lorem ipsum of `content/some-other-article.md`, `some-article.md` and `markdown_overview.md`, which are Latin and not typos; `sreen` twice in `sass/_toc.scss`, where `$toc-max-sreen-width` is declared on line 3 and used on line 55; and `eigth` once, which is the file name `content/eigth_post.md`. The theme's `theme.toml` sets `min_version = "0.17.0"`, `config.toml` turns on `compile_sass`, and `.github/workflows/docs.yml` is the only workflow: it builds and deploys the demo site on a push to `master` with `shalzz/zola-deploy-action@v0.17.2`.

The real fix is the Sass variable: the agent renames `$toc-max-sreen-width` to `$toc-max-screen-width` in both places in `sass/_toc.scss`, and since Zola compiles the Sass on build, runs `zola build` to confirm the stylesheet still compiles and the generated `site.css` is byte-identical apart from nothing, because a variable name does not reach the output. The file name is different: `content/eigth_post.md` sets the demo page's URL, `/eigth-post/`, which is published at the theme's demo site, so renaming it would move a page. The agent leaves the file name alone, lists it in the pull request with the two options, rename with a redirect or keep, and adds it to the ignore list so the check is green either way.

The config goes in `_typos.toml` at the root. It extends the dictionary with the three Latin words as identifiers to accept, excludes nothing by path, because the filler lives in files that also hold English prose worth checking, and lists `eigth_post.md` under the file-name exceptions. With that in place `typos` exits 0 on the fixed tree, and a new misspelling in a template, a post or the README fails it, which the agent proves by adding one to `README.md`, running the check, reading the failure and reverting.

The CI step is a second workflow, `.github/workflows/typos.yml`, running on pull requests and on pushes to `master` with `crate-ci/typos` pinned to the same release the agent ran, so the result in CI matches the result on a laptop. It stays separate from `docs.yml` because that workflow deploys and should not change for a spelling check. The README gets one line on how to run the check locally and how to accept a word.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a typo check to this Zola theme. Install typos-cli and run it on the whole checkout first; read theme.toml, config.toml, README.md, the templates and sass directories and .github/workflows/docs.yml. Fix every finding that is a real misspelling in source, including the Sass variable in sass/_toc.scss, and run zola build to confirm the site and the Sass still compile. Do not rename content files whose name sets a published URL; list them in the pull request instead and add them to the file-name exceptions. Write _typos.toml that accepts the Latin filler words as identifiers rather than excluding the files that contain them, prove the check fails on a deliberate misspelling and then revert it, and add .github/workflows/typos.yml running crate-ci/typos pinned to the release you ran, on pull requests and pushes to master, separate from the deploy workflow. Document the local command in README.md and open a pull request with the before and after 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 changes `sass/_toc.scss`, adds `_typos.toml` and `.github/workflows/typos.yml`, and adds a line to `README.md`. Its description pastes the first `typos` run with its 15 findings grouped by file, the run after the fix and the config with zero findings, the `zola build` output, and the one deliberate failure that shows the check works.

From then on a pull request that introduces a misspelling in a template, a Sass file, a post or the README fails the `typos` workflow with the file, line and suggested word, and the deploy workflow is untouched. The Latin posts stay as they are, because the words are accepted by name rather than the files being skipped, so a real typo in the English sentences around them is still caught.

Before merging, a reviewer decides what to do about `eigth_post.md`, whether to keep the URL or rename the file and add a redirect, and checks that the accepted words list is short enough to read, since every entry is a word the checker will never flag again.

## Run it on every site whose spelling is checked by eye

A team with several Zola sites or themes starts one run per repository from the terminal: one `POST /o/{org}/sessions` each with that repository in `resources` and a `request_id` that is a UUID v5 of its full name, so a retried call returns the run already started. Each run reads its own findings: a documentation site with code samples gets identifiers accepted per file, a multilingual site gets the non-English content excluded by locale directory, and a repository that already carries `_typos.toml` gets only the workflow and the fixes.

Each run opens its own pull request on its own branch, and `GET /o/{org}/sessions` lists them newest first, so the person who started the batch reads every before-and-after count from one place.

## Why run it on Rush?

A spelling check that is added blind either fails on the first run because of placeholder text, and gets a path exclusion that hides real typos in the same files, or is tuned so loosely it catches nothing. The agent runs the tool first, reads each finding, fixes the real ones, accepts the false ones by word, and proves the result both ways in its sandbox, with the outputs kept for the reviewer.

The run keeps every command and its output, so the reviewer sees the 15 findings, the fix and the clean run without installing `typos` or Zola. Several sites can be checked at once, each in its own sandbox, and one that is already clean gets the workflow and a note rather than an empty config.

## Frequently asked questions

### Why accept words instead of excluding the files?

The posts that hold the Latin filler also hold English headings and sentences. Excluding them by path would skip those too. Accepting `varius`, `Nam` and `facilisi` as identifiers removes the three false positives and keeps the files under the check.

### Does renaming the Sass variable change the built CSS?

No. Sass variables exist only at compile time, so `site.css` comes out the same, and `zola build` in the run shows the stylesheet compiling. The rename makes the source readable; it has no effect on visitors.

### What about the misspelled file name?

`content/eigth_post.md` sets the demo page's address, so renaming it moves a published page. The agent leaves the name, adds it to the file-name exceptions, and puts the choice in the pull request: keep the URL, or rename and add a redirect in the page's front matter. Either way the check stays green.

### Why pin the typos release in CI?

Each release of the checker ships a larger dictionary, so an unpinned action can start failing on a pull request that changed nothing. Pinning to the release the agent ran makes the CI result match the local one, and a later bump is a deliberate change with its own findings to review.

## More Zola jobs

- [Add a Build Check for Every Pull Request to a Zola Site](https://getrush.ai/run/add-build-check/zola/)
- [Add Dark Mode to a Zola Theme](https://getrush.ai/run/add-dark-mode/zola/)
- [Add Giscus Comments to a Zola Blog](https://getrush.ai/run/add-giscus-comments/zola/)

## The same job on other stacks

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

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