All jobs

Add Link Checking to a Zola Site

Yes. An agent turns on Zola's own link checker, adds a workflow that runs `zola check` on every pull request and once a week, 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 the site before it adds a check, because Zola already ships the checker and the only questions are where it runs and what it is allowed to skip. In a site on the Terminimal theme, as in pawroman/zola-theme-terminimal, config.toml sets base_url, compile_sass = true, generate_feeds = true with feed_filenames = ["rss.xml", "atom.xml"], a tags taxonomy, a [markdown] table with highlight_code = true and an [extra] table with five menu_items; there is no [link_checker] table. The theme is its own demo site, with config.toml and content/ at the repository root, so every command runs there. content/ holds five posts and three pages, and the external links in them are few: i-dont-like-javascript.md links to wtfjs.com, and welcome-terminimal-theme.md passes two image addresses, one on rustacean.net and one on upload.wikimedia.org, to the theme's figure and image shortcodes. .github/workflows/publish-pages.yml is the only workflow: it runs on a push to master, checks out with actions/checkout@v3.0.0 and builds and deploys with shalzz/zola-deploy-action@master. Nothing runs on a pull request, so a broken link reaches the published site before anyone sees it.

Zola's check subcommand builds every page as build would, writes nothing to disk, and fetches every external link in the Markdown files; the documentation notes that links in template files are not checked, and that --skip-external-links turns the fetching off and --drafts includes drafts. Internal links written as @/some-post.md are resolved during that same build, so a renamed post fails the check too. The agent runs zola check first in its own sandbox, after installing the Linux build from the v0.23.6 release on GitHub, the current one, and reads what comes back for the links above. The src values given to the shortcodes come out as HTML rather than Markdown links, so the pull request says, from the command's own output, whether they were fetched. Where a host refuses automated requests, the agent adds its prefix to skip_prefixes in a new [link_checker] table, with a comment saying why, rather than lowering external_level from error to warn for the whole site; the configuration reference lists skip_prefixes, skip_anchor_prefixes, internal_level and external_level as the table's keys.

The workflow goes in .github/workflows/check.yml. It runs on pull_request, on a push to master, and on a weekly schedule, because links rot after a post is merged and a check that only runs on changes never catches that. Its single job checks out the repository, downloads zola-v0.23.6-x86_64-unknown-linux-gnu.tar.gz from the Zola release page, verifies the download against the checksum printed in the pull request, unpacks it onto the path and runs zola check. The version is a workflow variable at the top of the file so the next upgrade is one line, and the agent notes that theme.toml sets min_version = "0.11.0" and the README says the theme was tested with Zola v0.19.2, so the pull request names the version it used. The existing publish workflow is not touched: deploying and checking stay separate, so a failed check on a pull request blocks nothing but that pull request.

For a site that uses the theme from themes/terminimal as a submodule, as the README suggests, the same workflow needs submodules: true on the checkout step, and the agent writes that variant when it finds a .gitmodules file. It also adds a short section to the README under the existing build badge: how to run zola check locally, that zola serve and zola build do not fetch external links, and how to add a prefix to skip_prefixes when a host blocks the checker. The last step is to open a pull request on master, with the zola check output from the sandbox in its description, the list of links it fetched and any prefix it had to skip.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add link checking to this Zola site. Read config.toml, theme.toml, the README, every file under content/ and .github/workflows/ first. Install the current Zola release in the sandbox and run zola check at the repository root; record which external links it fetched and which failed. Add a [link_checker] table to config.toml only if a host refuses automated requests, putting that prefix in skip_prefixes with a comment; keep internal_level and external_level at their defaults. Add .github/workflows/check.yml that runs on pull_request, on push to the default branch and on a weekly schedule, downloads the pinned Zola release tarball, verifies its checksum and runs zola check. Do not change the existing publish workflow. Add a short README section on running the check locally and on skipping a host. Open a pull request with the zola check output and the list of links it fetched.",
  "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/check.yml, a README section and, only when a host had to be skipped, a [link_checker] table in config.toml. Its description quotes the zola check output from the sandbox: the number of pages it built, each external link it fetched with the status it got, and the Zola version used. The publish workflow is unchanged, and .gitignore still keeps public/ out of the repository, because zola check writes nothing there.

A reviewer checks three things. Whether the schedule's day and hour suit them, since a weekly run that fails opens no issue by itself and someone has to read it; whether any prefix in skip_prefixes should instead be fixed in the post; and whether the Zola version pinned in the workflow matches what the publish action uses, so that a page that passes the check builds the same way on deploy. Pulling the branch and running zola check locally gives the same result as the workflow, which is the point of using Zola's own checker rather than a separate crawler.

Run it on every Zola site without a link check

A team with several Zola sites sends this body once per repository from its own server, each POST /o/{org}/sessions naming one 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 config.toml and content: a site that already has a [link_checker] table keeps it, a site whose theme lives in a submodule gets the checkout variant, and a site with drafts gets a note in the pull request that zola check skips them unless --drafts is passed.

The key's webhook_url reports each run the key starts with the pull request URL in result, so a script that sent eight requests collects eight pull requests without polling, and a run that found no external links at all still opens one, with the workflow and a description saying so.

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

Why run it on Rush?

A link check is only trustworthy once it has run against the real site, because what fails depends on the hosts the posts link to, and that is not visible from the files. The agent installs Zola, runs zola check in its own sandbox before writing the workflow, and keeps every command and its output in the run's record, so the pull request shows which links were fetched and which host, if any, had to be skipped, instead of a workflow whose first run on the reader's repository is also its first test.

The change is fitted to the repository rather than pasted in: the workflow pins the Zola version the sandbox used, the checkout step matches whether the theme is vendored or a submodule, and the publish workflow is left alone so deploys keep working while the check is reviewed. Ten sites on ten themes get ten pull requests, each with its own list of fetched links.

Frequently asked questions

Does this need a separate link-checking tool?

No. zola check is part of the Zola binary and fetches external links as part of a build that writes nothing to disk. The workflow installs Zola from its release page and runs that one command, so there is no other dependency to keep up to date.

Will it check links in my templates?

No. Zola's documentation says check fetches the external links in Markdown files and not those in template files, so a link in templates/index.html or in a menu entry under [extra] is not covered. The pull request says so, and lists the shortcode image addresses with whatever the command reported for them.

What happens when a site I link to blocks the checker?

The agent sees it in the sandbox run first. It adds that host's prefix to skip_prefixes in a [link_checker] table with a comment, so the rest of the site is still checked at the error level, and the pull request names the host so a reviewer can decide to replace the link instead.

Why run it on a schedule as well as on pull requests?

A link that worked when the post was merged can stop working months later, and nothing in the repository changes when it does. The weekly schedule catches that; a failed scheduled run shows in the Actions tab and in the README badge if one is added, and the pull request explains how to read it.

Does it slow down the publish workflow?

No. The check is a second workflow and the publish workflow is unchanged. A pull request has to pass the check, but a push to the default branch still builds and deploys as before, and the check runs beside it rather than in front of it.

More Zola jobs

The same job on other stacks

Keep reading