All jobs

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

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

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

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

The same job on other stacks

Keep reading