# Check for Broken Links in an Eleventy Site's CI

Yes. An agent adds an offline lychee check over your built Eleventy site to every pull request, a weekly job for external links, fixes what it finds and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-link-checking/eleventy/). Opens 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 where its links come from before it adds a checker, because an Eleventy site rewrites links at build time and a check on the sources would miss what readers click. In a site made from 11ty/eleventy-base-blog, `npm run build` is `npx @11ty/eleventy` with `content` as input and `_site` as output, on Node 22 from `.nvmrc`, and `eleventy.config.js` loads `InputPathToUrlTransformPlugin`, which turns `href="blog.njk"` in `content/index.njk` and `href="index.njk"` in `content/404.md` into real URLs in the HTML, and `HtmlBasePlugin`, which prefixes every absolute link when `build-ghpages` passes `--pathprefix=/eleventy-base-blog/`. The feed lives at `/feed/feed.xml`, tag pages at `/tags/<tag>/`, and images pass through from `public/`. External links are few and telling: `content/404.md` lists hosting guides on 11ty.dev, GitHub, GitLab, Netlify, Cloudflare and Vercel, `_includes/layouts/base.njk` links `https://www.11ty.dev/` in the footer, and `_data/metadata.js` and the feed's `base` in the config point at `https://example.com/`, a placeholder that a checker must not report.

The only workflow is `.github/workflows/gh-pages.yml.sample`, which deploys on pushes to `main` with every action pinned by commit SHA and a version comment, and `.github/dependabot.yml` updates npm monthly while its `github-actions` block is commented out. The agent adds `.github/workflows/links.yml` with two jobs. On pull requests and pushes it builds with the plain `npm run build`, so links are root-relative without a path prefix, and runs `lycheeverse/lychee-action`, pinned the same way as the sample, with `--offline` and `--root-dir _site` over `_site/**/*.html` and the feed, so a renamed post, a mistyped tag URL or a missing image fails the check in seconds without touching the network. On a weekly `schedule` a second job runs lychee without `--offline` on the same build, retries the hosts that rate-limit and uploads `lychee/out.md` as an artifact, since external links rot on their own schedule and should not block a pull request about a typo.

A `.lycheeignore` excludes `example.com`, the `mailto:` placeholder in `metadata.js` and the hosting providers' anchors that return 403 to robots, each with a comment saying why, and the agent uncomments the `github-actions` block in `dependabot.yml` so the new action gets the same monthly updates as npm. It also notes that `fifthpost.md` carries `draft: true` and the `drafts` preprocessor drops it from a build, so links in drafts are not checked until they publish.

To prove the setup, the agent installs with `npm ci`, builds, and runs lychee in its sandbox in both modes, first offline, then online once, and reads the results. Anything the offline run reports in the site's own pages it fixes in the content or templates in the same branch; anything the online run reports it lists in the pull request with the status code, fixing only the ones with an obvious replacement, such as a moved documentation page.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "codex",
  "input": "Add broken link checking to this Eleventy site's CI. Read eleventy.config.js, package.json, .nvmrc, the templates under _includes, the content directory, .github/workflows and .github/dependabot.yml first. Build the site with npm run build and run lychee over _site in your sandbox. Add a workflow with an offline check of the built site, using _site as the root directory, on every pull request and push, and a weekly job that checks external links and uploads its report. Add a .lycheeignore for placeholder domains with a comment per entry, pin the action by commit like the existing sample workflow, enable Dependabot for GitHub Actions, fix any broken internal links you find, list external failures with their status codes, and open a pull request.",
  "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

What comes back is a pull request on its own branch adding `.github/workflows/links.yml` and `.lycheeignore`, uncommenting the `github-actions` block in `.github/dependabot.yml`, and changing content or templates only where the offline check found a broken internal link. `eleventy.config.js`, the layouts and the deploy sample are otherwise untouched.

The description quotes lychee's summary lines from both sandbox runs, the count of links checked and the count excluded, lists every external failure with its status code and whether it was fixed or left, and explains the two-job split in a sentence: internal links block, external links report. It also says where the weekly report lands and how to make it open an issue instead if the team prefers.

Before merging, a reviewer reads the ignore file to confirm each entry is a placeholder and not a real broken link, opens the pull request's link check to see it pass, and decides whether the weekly job should fail or only report.

## Run it on every new content site in your organization

A handler on your server receives GitHub's organization `repository` event, checks its signature, and when the new repository has an `eleventy.config.js`, sends this body to `POST /o/{org}/sessions` with the repository in `resources`; GitHub signs its webhooks and cannot add the `Authorization` header a Rush `webhook` trigger needs, so it does not call the trigger directly. The handler sends a `request_id` that is a UUID v5 of the delivery id, so GitHub's redeliveries return the run already started.

With a `webhook_url` on the key, Rush POSTs `run.completed` when the turn ends, and the handler reads the pull request from the session. Every new site then starts with its internal links checked on each pull request and its external links reported weekly, with the transcript showing what the first check found.

## Why run it on Rush?

A link checker on an Eleventy site is a few lines of YAML and several ways to get them wrong: checking sources instead of output, checking a path-prefixed build against the root, letting a placeholder domain fail every run, or letting one dead external page block every pull request. The agent reads the build pipeline and the real links first and splits the job the way the failures split.

On Rush the build and both lychee runs happen in the agent's own sandbox, and the transcript keeps their output, so the pull request's list of what was broken and what was fixed is backed by the runs that found it. Many sites can be checked the same day, each in its own sandbox with its own pull request.

## Frequently asked questions

### Why check the built site rather than the Markdown?

Because the HTML is what readers get. The input-path transform rewrites `blog.njk` into a URL at build time, tag pages and the feed exist only in `_site`, and the base plugin can add a path prefix. Checking `_site` with `--root-dir _site` resolves every root-relative link the way the server would.

### Will a dead external link fail my pull request?

No. The pull request job runs offline and only checks links inside the site, which are the ones a change can break. External links are checked by the weekly job, which uploads a report; the pull request shows how to make that job open an issue or fail if the team wants it louder.

### What goes in .lycheeignore?

Placeholders and known false positives only, each with a comment: `example.com` from `metadata.js` and the feed configuration, the `mailto:` placeholder, and hosts that answer robots with 403. A real broken link is fixed or listed in the pull request, never ignored.

### Does the deploy workflow change?

No. The GitHub Pages sample keeps building with the path prefix and deploying on pushes to `main`. The link workflow builds separately without the prefix so internal links resolve against the site root, and only the `github-actions` entry in `dependabot.yml` is turned on so both workflows get action updates.

## More Eleventy jobs

- [Add an llms.txt File to an Eleventy Site](https://getrush.ai/run/add-llms-txt/eleventy/)
- [Add Mermaid Diagrams to an Eleventy Blog](https://getrush.ai/run/add-mermaid-diagrams/eleventy/)
- [Add Open Graph and Twitter Card Tags to an Eleventy Blog](https://getrush.ai/run/add-open-graph-tags/eleventy/)

## The same job on other stacks

- [Check for Broken Links in a Hugo Site's CI](https://getrush.ai/run/add-link-checking/hugo/)
- [Add Link Checking to a Jekyll Site with html-proofer](https://getrush.ai/run/add-link-checking/jekyll/)
- [Add External Link Checking to an mdBook](https://getrush.ai/run/add-link-checking/mdbook/)

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