All jobs

Add a Typo Check to a Pelican Site

Yes. An agent runs the typos checker over a Pelican site's content and theme, writes a config that skips fonts and vendored CSS, adds a 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 looks at what a spell checker would read before it adds one. In a Pelican site like getpelican/pelican-blog, the prose is 18 reStructuredText release announcements under content/news/, from pelican-3.0.rst to pelican-4.7.rst plus i18n_subsites_released.rst, sprint-2019-fall.rst and heroku-buildpack-pelican.rst, one Markdown post, namespace-plugins.md, and three pages under content/pages/. Each article is full of names a dictionary does not know: contributor handles in the release notes, package names like typogrify and docutils, and the .. _release page: link targets reStructuredText uses. Beside the prose sit things a checker should not read at all: themes/notmyidea/static/css/ with pygment.css and typogrify.css, a fonts/ directory, the touch icons and robots.txt under content/extra/, and content/logo/ with the SVG logo. pelicanconf.py and publishconf.py hold settings, the Makefile the build, and there is no .github/ directory and no CI of any kind.

The agent picks typos, the Rust checker that works from a list of known misspellings rather than a dictionary, so names and handles pass unless they match a known mistake. It downloads the current release binary and runs it over the whole tree first, with no config, and reads every finding with its file and line, because what it reports decides the config. Findings inside themes/notmyidea/static/ are the minified CSS and font names and are not typos; findings in content/extra/ and content/logo/ are binary and SVG noise. Those directories go under files.extend-exclude in a new _typos.toml. A finding in an article or page is either a real misspelling, which the agent fixes in the source and lists, or a deliberate spelling such as a project name or a handle the checker's list happens to match, which goes under default.extend-words with the word spelled as the site wants it, and the pull request says which of the two each one was.

The workflow is one job. .github/workflows/typos.yml runs on pull_request and on pushes to the default branch, checks the repository out and runs the crate-ci/typos action pinned to a commit with its version in a comment, pointing it at _typos.toml. It is the first workflow in the repository, so the agent keeps it small and says in the pull request that the make publish build could join it as a second job. It runs the binary a second time with the finished config to confirm the result is clean, which is also the output the pull request quotes.

Because contributors write in reStructuredText, the agent also checks that typos is not confused by the markup: a .. _target: label, a `link text <url>`_ reference and an :slug: field each pass, and the few that produced a finding on the first run show the fix in the config. Nothing in pelicanconf.py, the theme templates or the Makefile is changed.

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 Pelican site. Read pelicanconf.py, the Makefile, the content tree and the theme directory first, and note which paths hold prose and which hold fonts, CSS, images and icons. Download the current typos release and run it over the whole repository with no config; read every finding with its file and line. Write _typos.toml that excludes the theme's static files and the content directories that hold images and icons, fixes real misspellings in the source, and adds deliberate spellings such as project names and contributor handles to the allowed words, saying in the pull request which finding was which. Add .github/workflows/typos.yml on pull requests and pushes to the default branch, running the crate-ci/typos action pinned to a commit with the config. Run typos again with the final config and open a pull request that quotes the first and the final run.",
  "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

A pull request with _typos.toml, .github/workflows/typos.yml and whatever misspellings it fixed in content/. Its description has the first run's findings grouped into excluded paths, real fixes and allowed words, and the final run's clean output, so a reviewer sees what the check will enforce and what it was told to ignore.

A reviewer checks that every allowed word is a spelling the site means, which the list beside each one answers, that no excluded path holds prose, and that the fixes in the release notes change nothing but spelling. Once merged, the workflow runs on the next pull request and marks a new typo in its files tab.

Run it on every terminal hand-off

A maintainer who has just fixed a typo in a two-year-old release note starts this from the terminal with this body and the repository in resources, and goes back to the next one. The run reads the real tree, so the exclusions and allowed words come from what the checker found in these files rather than a generic list.

Send a request_id, a UUID, with the body so a retried start returns the run it already began. When the turn ends, GET /o/{org}/sessions/{id} names the pull request, and a follow-up to the same session can ask for the site build as a second job in the workflow, or for a make typos target that runs the same binary locally.

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

Why run it on Rush?

What makes this job real is the first run over the actual files, with its findings read one by one and sorted into fixes, allowed words and paths to skip. The agent does that in its own sandbox with the binary downloaded there and keeps both runs in the run's record, so the pull request shows what the check will say on the next pull request rather than assuming a clean tree.

The same run fits any static site: a Hugo blog with vendored themes, a Sphinx manual with code samples, a documentation site with translated pages that need their own allowed words. Each gets a config derived from its own findings and a workflow pinned the way its other workflows are, or a first one when it has none.

Frequently asked questions

Why typos rather than a dictionary-based checker?

A dictionary flags every contributor handle, package name and link target in a site like this, and the allow list grows past the content. typos matches a list of known misspellings, so names pass unless they happen to look like one, and the config stays short.

Will it rewrite my release notes?

Only where a word is a real misspelling, and each one is listed in the pull request with its file and line. Deliberate spellings go into the config's allowed words instead, so the source keeps them.

Can the check fail on a theme file?

The theme's static CSS and fonts are excluded in _typos.toml, so no. Template files under themes/notmyidea/templates/ are still checked, since their text is what visitors read; a finding there is treated like one in the content.

How do I run it before I push?

Download the same release the workflow uses and run typos from the repository root; it reads _typos.toml on its own. A follow-up can add a make typos target or a pre-commit hook so it runs with the rest of the site's tooling.

More Pelican jobs

The same job on other stacks

Keep reading