All jobs

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

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

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

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

The same job on other stacks

Keep reading