# Add External Link Checking to an mdBook

Yes. An agent adds a scheduled lychee workflow to an mdBook that checks outbound links with a cache and an ignore file, runs it once in its sandbox and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-link-checking/mdbook/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

An mdBook's CI often checks links already, so the agent reads what the existing check covers before adding another. In a book laid out like rust-lang/rust-by-example, `book.toml` names the title, sets `edit-url-template` and `git-repository-url` under `[output.html]`, enables the editable playground and folding, adds `theme/css/language-picker.css`, and declares an optional `gettext` preprocessor for the translations under `po/`. `.github/workflows/rbe.yml` is the one workflow: it installs a pinned `mdbook` from the release tarball and `mdbook-i18n-helpers` through `cargo install`, runs `mdbook test` and `mdbook build`, then downloads `linkcheck.sh` from the `linkchecker` tool in rust-lang/rust and runs it against the built `book` directory, once for the source and once per language in `LANGUAGES`. That tool checks the links inside the built HTML against the local tree and the installed `rust-docs`; it never fetches an `http` or `https` address. So the book's outbound links, the ones to crates, blog posts and external references scattered through the Markdown under `src/`, are never checked, and they are the ones that rot.

The agent writes `.github/workflows/links.yml` around `lycheeverse/lychee-action`, pinned to its current major. It runs on a weekly `schedule`, on `workflow_dispatch`, and on `pull_request` for changes under `src/`. The step restores a `.lycheecache` with `actions/cache/restore`, runs lychee with `--cache --max-cache-age 1d` so a link that answered yesterday is not fetched again, `--root-dir` set to the checkout so absolute paths resolve, and the inputs `src/**/*.md` and `README.md` while excluding `po/`, whose `.po` files repeat every link once per language. On the schedule the step has `fail: false` and is followed by `peter-evans/create-issue-from-file` with `issues: write`, so a broken link becomes one issue with lychee's Markdown report rather than a red badge nobody reads; on a pull request `fail` is left on so a new dead link blocks the merge. The cache is saved with `actions/cache/save` under `if: always()`, the pattern the action's README recommends so a failing run still updates it.

Two files shape what lychee ignores. `.lycheeignore` lists patterns that cannot or should not be fetched from a runner: `play.rust-lang.org` links, which the editable playground generates and which carry code in the query string, `localhost` and `127.0.0.1` examples, and any address the book uses as a placeholder. `lychee.toml` sets `accept` to include the status codes GitHub returns for rate limiting, a `max-retries` and `timeout`, a `user-agent`, and `exclude-loopback`, and the workflow passes the repository's `GITHUB_TOKEN` as `token` so links to github.com are not throttled. `.lycheecache` is added to `.gitignore`. The agent does not touch `rbe.yml`; the local-link check it runs is a different job and stays.

To see what the first run will report, the agent installs lychee in its sandbox from the project's release and runs `lychee --no-progress --root-dir . 'src/**/*.md' README.md` with the same ignore file and config, then runs it a second time with `--cache` to show the second pass is quick. The pull request pastes the summary line and lists every address lychee reports as broken, timed out or excluded, grouped by file, so the first scheduled run on GitHub holds no surprises. The agent fixes none of those links itself; which address to update and which to drop is an editorial call for the book's maintainers.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add external link checking to this mdBook. Read book.toml, .github/workflows/rbe.yml, README.md, CONTRIBUTING.md, .gitignore and the layout of src, theme and po first, and say in the pull request what the existing linkcheck.sh step does and does not cover. Write .github/workflows/links.yml using lycheeverse/lychee-action on a weekly schedule, workflow_dispatch and pull requests that touch src, with a restored and always-saved .lycheecache, --cache --max-cache-age 1d, --root-dir set to the checkout, src/**/*.md and README.md as inputs, po excluded, the GITHUB_TOKEN passed as token, fail false plus peter-evans/create-issue-from-file on the schedule and fail true on pull requests. Add a .lycheeignore for playground, localhost and placeholder addresses and a lychee.toml with accept codes, retries, timeout and user agent. Add .lycheecache to .gitignore. Install lychee in the sandbox, run it twice to show the cache, and open a pull request listing every link it reports, grouped by file, without fixing any.",
  "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/links.yml`, `.lycheeignore` and `lychee.toml`, and adds one line to `.gitignore`. Its description explains the gap between the existing `linkcheck.sh` step and outbound links, pastes lychee's summary from the sandbox run and the shorter second run with the cache, and lists each reported address under the Markdown file that contains it.

The pull request itself triggers the new workflow when it touches `src/`, which it does not, so the first run is the one a maintainer starts from the Actions tab with `workflow_dispatch` or the first weekly schedule; its Markdown report lands as an issue. The run's record on Rush keeps both sandbox invocations so the list in the pull request can be checked against lychee's own output.

Before merging, a reviewer picks the schedule day, decides whether pull requests should block on a dead outbound link or only report, and goes through the listed addresses to fix or ignore each. The book's content and the existing CI workflow are unchanged.

## Run it on every mdBook repository whose outbound links go unchecked

An organisation with several books starts one run per repository from its own server: a `POST /o/{org}/sessions` each, with the repository in `resources` and 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 `book.toml` and workflows, so a book that already runs lychee gets a report of what its configuration misses, and a book with no CI at all gets the local-link check proposed in the same pull request.

The scheduled workflow does the weekly checking on GitHub. For the follow-up, an automation in the Project with a `github` trigger on `issues.labeled`, filtered to a `fix-links` label, and the prompt "if this issue is a Link Checker Report, open a pull request that updates each moved link to its new address where the redirect target is clear and lists the rest for a maintainer" turns the report into a reviewable change once a maintainer adds that label to the report. The trigger adds the issue after the prompt and fires only for work by owners, members and collaborators; the issue the workflow opens with its own token comes from a bot sender, which never fires a trigger, so the maintainer's label is what starts the run.

## Why run it on Rush?

Link checking is one of those jobs where the configuration is the work: without a cache the weekly run hammers the same hosts and trips rate limits, without an ignore file every playground link fails, and without `fail: false` on the schedule the badge turns red the first week and stays red. The agent reads what the book already checks, runs lychee for real in its sandbox against the actual Markdown, and ships the workflow with the first report already in hand.

Every command stays with the run, including both lychee passes, and the pull request quotes them. Several books get the same workflow at once, each checked on its own machine with its own list of addresses.

## Frequently asked questions

### Does this replace the existing linkcheck.sh step?

No. That step checks the links inside the built HTML against the local tree and the `rust-docs` component, which catches a broken anchor or a renamed chapter. Lychee fetches outbound `http` and `https` addresses, which that tool skips. The two jobs are complementary and the pull request keeps both.

### Why run the schedule with fail false and open an issue?

Because an outbound link breaks on someone else's server at any time, and a red scheduled workflow is easy to ignore. An issue with lychee's Markdown report is something a maintainer triages. On pull requests the check fails, since a new dead link is the author's to fix.

### What goes in .lycheeignore?

Addresses that cannot or should not be fetched from a runner: the playground links the editable code blocks generate, `localhost` examples, and placeholder domains used in prose. The agent lists each pattern with the reason in a comment, and the sandbox run shows what each one excludes.

### Will lychee check the translations?

Not by default. The `po/` directory repeats every link once per language in `.po` files, which would multiply the work and the noise without finding anything new. A team that wants the built translations checked can add the `book/<lang>` output as a second input once the book is built in the same job.

## More mdBook jobs

- [Add llms.txt to an mdBook Site](https://getrush.ai/run/add-llms-txt/mdbook/)
- [Add Mermaid Diagrams to an mdBook](https://getrush.ai/run/add-mermaid-diagrams/mdbook/)
- [Add Open Graph Tags to an mdBook Site](https://getrush.ai/run/add-open-graph-tags/mdbook/)

## The same job on other stacks

- [Add Link Checking to an MkDocs Site](https://getrush.ai/run/add-link-checking/mkdocs/)
- [Add Link Checking to a Pelican Blog](https://getrush.ai/run/add-link-checking/pelican/)
- [Check for Broken Links in Sphinx Docs with the linkcheck Builder](https://getrush.ai/run/add-link-checking/sphinx/)

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