# Add a Typo Check to a Hugo Site

Yes. An agent turns the cspell config your Hugo site already carries into an npm script and a CI job, fixes the misspellings it finds, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-typo-check/hugo/). 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 site is built and checked before it adds anything. In a site laid out like docsy/docsy-example, `hugo.yaml` declares three languages, `en` in `content/en`, `no` in `content/no` and `fa` in `content/fa`, pulls the Docsy theme as a Hugo module through `go.mod`, and `package.json` pins `hugo-extended` at `0.166.0` beside `prettier`, `sass-embedded` and `link-cache`, with `engines` requiring Node 24 and npm 11.18 and `.nvmrc` at `24.22.1`. The scripts follow a naming rule: `_check:format` runs Prettier, `check:links` builds the site and runs lychee, `test:site` runs `node --test` over `tests/*.test.mjs`, and `ci:test` chains `ci:prepare`, `fix:format`, `test` and `_diff:check`. One of those tests, `tests/npm-scripts.test.mjs`, refuses any script whose name starts with `pre` or `post`, so a new script has to be named like the others. `.github/workflows/links.yaml` and `zizmor.yaml` are the only workflows, each pinning its actions by commit SHA with a version comment and checking out with `persist-credentials: false`, and `.npmrc` sets `strict-allow-scripts=true`, `min-release-age=7` and `engine-strict=true`.

Spelling is half done already, which is the point. `.cspell.yml` at the root sets `version: '0.2'`, `caseSensitive: true` and ten `words` such as `docsy`, `hugoautogen`, `gohugoio` and `Goldydocs`; `hugo.yaml` starts with a `# cSpell:ignore` line and wraps the Norwegian and Persian language blocks in `# cSpell:disable` and `# cSpell:enable`; `package.json` carries a `spelling` field reading `cSpell:ignore docsy hugo rtlcss -`; `renovate.jsonc` ends with its own ignore comment. Nothing runs cspell: it is not in `devDependencies`, no script calls it and no workflow does. The agent keeps that configuration rather than introducing a second checker whose directives would ignore every one of those comments, adds `cspell` to `devDependencies` pinned to an exact version as the file pins everything else (it has no install script, so `allowScripts` stays as it is), and extends `.cspell.yml` with `ignorePaths` for `node_modules`, `public`, `resources`, `package-lock.json`, `go.sum`, `docsy.work.sum`, `link-cache.jsonc`, `packages/hugoautogen`, `static` and the two non-English content trees, which an English dictionary would flag line by line.

The new script is `check:spelling`, running `cspell --no-progress --gitignore "**"`, and `test-only` becomes `check:links && check:spelling && test:site` so `ci:test` and `npm test` pick it up without a new entry point. The agent runs `npm run install:safe`, which is `npm ci --ignore-scripts`, then the script, and works through the report: a real misspelling in `content/en/docs` or `content/en/blog` is corrected in the file; a product or theme name that is spelled as intended goes into `words`; a term that appears in one file only gets an inline `cSpell:ignore` comment, the way `hugo.yaml` and `renovate.jsonc` already do it. Because `caseSensitive` is on, `Github` and `github` are different entries, and the agent fixes the capitalisation in prose rather than adding both. After the edits it runs `npm run fix:format` so Prettier, which `.prettierignore` keeps away from `content/fa`, `layouts` and `packages`, leaves nothing for `_diff:check` to complain about.

The CI job is a new `.github/workflows/spelling.yaml` with `permissions: contents: read`, `actions/checkout` pinned by SHA with `persist-credentials: false`, `actions/setup-node` reading `.nvmrc` with the npm cache, `npm run install:safe` and `npm run check:spelling`. It skips the full `npm ci` that `links.yaml` needs for the `hugo-extended` postinstall, so it reports in well under the time the link check takes, and the `github-actions` rule in `renovate.jsonc` will keep its pins current. The agent runs `zizmor` over the new workflow with the pedantic persona the repository uses, then `npm run ci:test` end to end, including a Hugo build with the real `npm ci`, to prove the corrected files still render before it opens the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a spelling check to this Hugo site and open a pull request. Read hugo.yaml, package.json, .npmrc, .nvmrc, .cspell.yml, .prettierignore, renovate.jsonc, tests/npm-scripts.test.mjs, every workflow under .github/workflows and the layout of content/ first. Keep the existing .cspell.yml and its in-file cSpell directives; add cspell to devDependencies pinned to an exact version, add ignorePaths for build output, lock and sum files, generated packages and the non-English content directories, and add a check:spelling script that runs cspell --no-progress --gitignore over the tree, wired into test-only so ci:test runs it. Never name a script with a pre or post prefix. Run npm run install:safe and the script; fix real misspellings in the English content, layouts and data files, add intended names to words, and use an inline cSpell:ignore comment for a term that appears in one file. Run npm run fix:format after editing. Add .github/workflows/spelling.yaml with contents: read permissions, actions pinned by commit SHA with version comments, persist-credentials false, Node from .nvmrc, npm run install:safe and npm run check:spelling. Run zizmor on the new workflow and npm run ci:test until both are clean, then open a pull request listing every correction as a before-and-after pair grouped by file, every word added and why, and every path ignored and why.",
  "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 `.github/workflows/spelling.yaml`, changes `package.json`, `package-lock.json` and `.cspell.yml`, and touches the English content, layout and data files where a word was corrected. Its description lists the corrections as before-and-after pairs grouped by file, the words added to `.cspell.yml` with the file that uses each, the paths ignored with a reason per line, and the output of `npm run check:spelling`, `zizmor` and `npm run ci:test` as they ran in the sandbox.

The Norwegian and Persian trees are listed as ignored rather than checked, and the description says so in one line next to the `# cSpell:disable` block in `hugo.yaml` that already made the same choice for the language names, so a maintainer sees the boundary was taken from the repository and not guessed.

Before merging, a reviewer scans the pairs for a spelling that was intentional, decides whether any word added to `words` should instead be a one-file ignore, and checks that the new job's pins and permissions match what `zizmor.yaml` enforces on the other workflows.

## Run it on every pull request

Once the job exists, an automation on the Project with a `github` trigger on `pull_request.synchronize` and the prompt "if the spelling job failed on this pull request, read its log and leave one review comment per file with the suggested corrections, 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 it fires only for pull requests from an owner, member or collaborator, so a contribution from a fork keeps its red check until a maintainer looks.

An organisation with several Docsy or other Hugo sites sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming that repository in `resources` and carrying a `request_id` that is a UUID v5 of the repository's full name, so a retry returns the run already started. Each run reads its own site: one with no `.cspell.yml` gets a fresh config written from its content, and one whose scripts are not under the `pre`/`post` ban gets a plain `spellcheck` script instead.

## Why run it on Rush?

A spell check on a documentation site is a judgement job, not a mechanical one: three in-file ignore directives, a case-sensitive dictionary, two non-English content trees and a test that polices script names all have to be respected, or the pull request either flags hundreds of correct words or breaks `ci:test`. The agent reads those rules out of the repository and proves the result by running the full `ci:test` chain, Hugo build included, in a sandbox with the exact Node and npm the `engines` field demands.

The cspell report, the formatter run, the zizmor output and the full CI chain stay with the run, so a reviewer can see why each word was added or each path ignored without reproducing it locally. A team that runs several Hugo sites sends the same request to all of them at once and reads one pull request per site.

## Frequently asked questions

### Why cspell rather than the typos checker?

Because the site already configured cspell: `.cspell.yml` exists, and `hugo.yaml`, `package.json` and `renovate.jsonc` carry `cSpell:ignore` and `cSpell:disable` comments that another tool would not read. Reusing it means the editor extension that wrote those comments and the CI job agree on every word.

### Does it check the Norwegian and Persian pages?

No. `content/no` and `content/fa` go into `ignorePaths`, because the English dictionary would flag most words in them, which is the same reason `hugo.yaml` wraps those language blocks in `# cSpell:disable`. A language-specific dictionary package can be added for either tree later as a separate change.

### Why does the job use `install:safe` instead of `npm ci`?

`install:safe` is `npm ci --ignore-scripts`. The spelling check needs cspell and nothing else, while a full `npm ci` runs the `hugo-extended` postinstall that downloads a Hugo binary. The links workflow needs that binary to build the site; the spelling job does not, so it finishes sooner and runs less code.

### Will it flag front matter keys, shortcodes and code blocks?

cspell splits camelCase identifiers like `linkTitle` into dictionary words, and the agent adds `ignoreRegExpList` patterns for shortcode calls and fenced code where the report shows them producing noise, rather than listing each token under `words`. Anything still reported is a real decision, listed in the pull request.

## More Hugo jobs

- [Add a Version Menu to a Hugo Docsy Site](https://getrush.ai/run/add-versioned-docs/hugo/)
- [Review Pull Requests on a Hugo Theme](https://getrush.ai/run/review-pull-requests/hugo/)
- [Add a GitHub Pages Deploy Workflow to a Hugo Site](https://getrush.ai/run/add-deploy-workflow/hugo/)

## The same job on other stacks

- [Add a Typo Check to a Jekyll Site in CI](https://getrush.ai/run/add-typo-check/jekyll/)
- [Add a Typo Check to an mdBook in CI](https://getrush.ai/run/add-typo-check/mdbook/)
- [Add a Spell Check to MkDocs Docs in CI](https://getrush.ai/run/add-typo-check/mkdocs/)

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