# 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 Rush](https://cloud.getrush.ai/run/add-link-checking/zola/). Opens 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`

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

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

- [Add llms.txt to a Zola Site With a Feed Template](https://getrush.ai/run/add-llms-txt/zola/)
- [Add Open Graph Tags to a Zola Site](https://getrush.ai/run/add-open-graph-tags/zola/)
- [Add Reading Time to a Zola Blog](https://getrush.ai/run/add-reading-time/zola/)

## The same job on other stacks

- [Check for Broken Links in an Astro Site's CI](https://getrush.ai/run/add-link-checking/astro/)
- [Find and Fix Broken Links in a Docusaurus Site](https://getrush.ai/run/add-link-checking/docusaurus/)
- [Check for Broken Links in an Eleventy Site's CI](https://getrush.ai/run/add-link-checking/eleventy/)

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