All jobs

Add a Typo Check to an Eleventy Blog in CI

Yes. An agent adds the typos checker to your Eleventy site, fixes what it finds in content, templates and CSS, adds its first CI workflow, 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 what already checks it. In a blog laid out like 11ty/eleventy-base-blog, package.json is version 9.0.0, type: module, with @11ty/eleventy ^3.1.8, @11ty/eleventy-img, the navigation, RSS and syntax-highlight plugins, luxon, zod and @zachleat/heading-anchors, and a build script of npx @11ty/eleventy; .nvmrc says Node 22. eleventy.config.js sets the input to content/, includes to _includes/, data to _data/ and output to _site/, pre-processes Markdown with Nunjucks, drops drafts at build time, bundles inline CSS and JS, and generates an Atom feed and optimised images. The content is four published posts and one draft under content/blog/, an about.md, the index.njk, blog.njk, tags.njk and tag-pages.njk templates, a sitemap.xml.njk, and three stylesheets under css/. .github/workflows/ holds only gh-pages.yml.sample, a deploy workflow that is inert until renamed, so there is no CI at all, and nothing checks spelling.

The agent installs typos-cli in its sandbox and runs typos . from the root before writing any config, because the first run tells it what the site is actually like. typos matches a table of known misspellings rather than a dictionary, so it does not stop on njk, luxon, prismjs or the navel-gazer in _data/metadata.js. On this blog it reports one finding, in css/index.css at line 138: a comment reads fom pushing content around, and the fix is from. The posts are placeholder prose, Leverage agile frameworks to provide a robust synopsis, which is spelled correctly, so the content comes back clean; a real blog with years of posts returns a longer list, and the agent fixes each in place and keeps the before and after for the pull request.

Config is a _typos.toml at the root with only what the site needs. files.extend-exclude lists package-lock.json, public/img/ and content/feed/, since a lockfile and a feed script are not prose, and _site/ is already ignored through .gitignore, which typos honours. default.extend-words is left empty unless the run found a real word the table mistakes, in which case the entry carries a comment naming the file that uses it. An identifier inside a fenced code block, such as the myCommand function in content/blog/firstpost.md's diff-js block, is never rewritten; if one trips the checker it goes under default.extend-identifiers with the file in a comment. The agent then runs npm ci and npm run build on Node 22 to confirm the fixed CSS and content still build, and reads the _site/ output of one changed page.

The workflow is the site's first. .github/workflows/typos.yml runs on pull_request and on pushes to main, with permissions: contents: read, one job that checks out the repository with persist-credentials: false and runs crate-ci/typos pinned to a release tag by commit, following the pinning style the sample deploy workflow already uses for actions/checkout and actions/setup-node. The agent runs actionlint on the file and typos once more until it exits zero, and leaves gh-pages.yml.sample as it found it, since enabling a deploy is a decision for the site's owner.

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 Eleventy site. Read package.json, .nvmrc, eleventy.config.js, _data/metadata.js, .gitignore and the layout of content/, _includes/, css/ and .github/ first. Install typos-cli and run typos from the root before writing any config, and keep the output. Fix each real misspelling in Markdown prose, Nunjucks templates and CSS comments in place; never change an identifier inside a fenced code block, record it under default.extend-identifiers with the file in a comment instead. Write _typos.toml with files.extend-exclude for package-lock.json, public/img/ and content/feed/, and default.extend-words only for words the run actually flagged, each with a comment. Run npm ci and npm run build on the Node version in .nvmrc after the edits. Add .github/workflows/typos.yml running crate-ci/typos pinned by commit to a release tag, on pull_request and on pushes to main, with contents: read permissions and persist-credentials off on the checkout. Leave gh-pages.yml.sample alone. Run actionlint and typos until both exit clean, then open a pull request listing every correction as a before-and-after pair with its file, and every config 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, fixes the misspellings the first run found, in this layout the one comment in css/index.css, and changes nothing in eleventy.config.js or package.json. Its description pastes the first typos run, the clean final run, the npm run build result, and a table of every correction with its file and line.

From the next pull request on, a misspelling in a post, a template or a stylesheet comment fails the typos check with the file, the line and the suggested word, and the author fixes it before review rather than after publication.

Before merging, a reviewer reads the corrections table, since a checker's suggestion is not always the word the author meant, confirms the pinned crate-ci/typos commit matches a release tag, and decides whether the workflow should also run on a schedule, which matters only once the typos table itself is updated.

Run it on every pull request

Once the workflow is in, every pull request runs the check on GitHub's own runners with no run on Rush at all. The run on Rush is the one that introduces it: a developer starts it from the terminal with this body and the site's repository in resources, and reads the corrections table when the pull request opens.

A team that maintains several Eleventy sites sends one POST /o/{org}/sessions per repository with 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 with an existing ci.yml gets the job added there, one whose posts are written in a language other than English gets that language's table enabled in _typos.toml, and one with a large archive gets its corrections grouped by year in the description.

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

Why run it on Rush?

The first pass of a spell checker over a site is a judgement job: which findings are typos, which are identifiers in code blocks, which are names the table is wrong about, and whether the fixes still build. The agent makes every call in the open, with a comment per config entry and a table per correction, and runs the same build the deploy will run so a mended template never breaks a page.

The run keeps the first typos output and the clean one, the build log and the actionlint result, so review is about the words rather than about whether the tooling works. Several sites can be onboarded at once, each in its own sandbox, each with its own table of corrections.

Frequently asked questions

Will it rewrite words in code blocks?

No. An identifier inside a fenced block is left as it is, and if the checker flags one it goes under default.extend-identifiers with a comment naming the file. The diff-js and js blocks in the sample posts hold myCommand and counter, which the table does not flag, so on this layout the list stays empty.

Why typos and not a full spell checker?

typos matches a table of known misspellings, so it has almost no false positives on a site full of plugin names, Nunjucks tags and class names, and it needs no dictionary of allowed words to get started. A full spell checker on this layout would flag njk, luxon and navel-gazer before it found the one real typo.

Does the check run on the built site?

No. It runs on the sources, and _site/ is skipped because .gitignore lists it and typos honours that file. The build runs in the sandbox only to confirm the corrected files still produce the site.

What if the sample deploy workflow is enabled later?

Nothing changes for the check. typos.yml is its own workflow on pull_request and pushes to main; renaming gh-pages.yml.sample adds a deploy beside it. The agent leaves the sample file untouched and says so.

What about drafts?

The draft post under content/blog/ is excluded from the build by the preprocessor in eleventy.config.js, but it is a source file, so the check reads it and a misspelling there is reported too. That is deliberate: a draft is fixed before it is published.

More Eleventy jobs

The same job on other stacks

Keep reading