# Add Link Checking to an MkDocs Site

Yes. An agent turns on MkDocs link validation with a strict build, adds a scheduled lychee workflow for outbound links, runs both in its sandbox and opens a PR.

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

## What the agent does

An MkDocs site has two kinds of links that rot in different ways, relative links between pages and outbound `https` addresses, and MkDocs itself only ever sees the first kind. So the agent reads the configuration to learn what the build already checks. In a project laid out like encode/httpx, `mkdocs.yml` sets `site_url`, the `material` theme with a `custom_dir` under `docs/overrides`, `repo_url` and an empty `edit_uri`, a `nav` of 23 pages across `docs/` and `docs/advanced/`, and three Markdown extensions, `admonition`, `codehilite` and `mkautodoc`. It has no `validation` block and no `strict` key. `requirements.txt` pins `mkdocs==1.6.1`, `mkautodoc==0.2.0` and `mkdocs-material==9.6.18`. `scripts/build` runs `python -m build`, `twine check dist/*` and a plain `mkdocs build`, and `.github/workflows/test-suite.yml` calls that script on every push and pull request across Python 3.9 to 3.13, after `scripts/install` and `scripts/check`. Nothing in the repository fetches an outbound address.

MkDocs 1.5 added a `validation` setting and 1.6 extended it, so on this pinned version the first layer costs no dependency. The agent adds a `validation` block to `mkdocs.yml` with `links.not_found`, `links.anchors`, `links.unrecognized_links` and `links.absolute_links` set to `warn`, and `nav.not_found` and `nav.omitted_files` likewise, then changes the `mkdocs build` line in `scripts/build` to `mkdocs build --strict`, which turns a warning into a failed build. It runs that build in the sandbox before writing anything else to see what the site already fails on, since a relative page or image path that no longer resolves is what `links.not_found` reports first. The pull request lists every warning the build raises, fixes the ones that are clearly a path typo and leaves the rest for the maintainers, because `--strict` is only useful once the build is green.

The second layer is a workflow. The agent writes `.github/workflows/links.yml` around `lycheeverse/lychee-action`, pinned to its current major, running on a weekly `schedule`, on `workflow_dispatch` and on `pull_request` for changes under `docs/`. The step restores `.lycheecache` with `actions/cache/restore`, runs lychee with `--cache --max-cache-age 1d` and `--root-dir` set to the checkout against `docs/**/*.md` and `README.md`, and saves the cache under `if: always()`. On the schedule the step has `fail: false` and `peter-evans/create-issue-from-file` with `issues: write` turns the report into one issue; on a pull request `fail` stays on so a new dead link blocks the merge. A `.lycheeignore` excludes what a runner cannot or should not fetch: `httpbin.org` and `www.example.com`, which the quickstart uses as sample hosts on dozens of lines, `localhost` and `testserver` addresses from the testing guide, and `myproxy.org`. `lychee.toml` sets `accept` codes, retries, a timeout and a user agent, and the workflow passes `GITHUB_TOKEN` so the many links to github.com are not throttled. `.lycheecache` goes into `.gitignore`.

To show what the first run reports, the agent installs lychee in its sandbox from the project's release and runs it twice against the same inputs, once cold and once with `--cache`, and pastes the summary of each. It counts what the docs point at before running: the Markdown under `docs/` carries 176 distinct outbound addresses, 54 of them on github.com and the rest spread across `docs.python.org`, `requests.readthedocs.io` and a handful of others, which is why the token and the cache matter. It also adds `scripts/docs-check`, a two-line script that runs `mkdocs build --strict` alone so a writer can check a page without building the package, and says in `docs/contributing.md` that the docs job now fails on a broken internal link.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add link checking to the MkDocs site in this repository. Read mkdocs.yml, requirements.txt, scripts/build, scripts/docs, .github/workflows/test-suite.yml, docs/contributing.md, .gitignore and the Markdown under docs first. Add a validation block to mkdocs.yml that sets the links and nav checks to warn, change scripts/build to run mkdocs build --strict, run that build in the sandbox, fix references that are plain path typos such as an image file that does not exist under docs/img, and list every remaining warning in the pull request. Add .github/workflows/links.yml using lycheeverse/lychee-action on a weekly schedule, workflow_dispatch and pull requests that touch docs, with a restored and always-saved .lycheecache, --cache --max-cache-age 1d, --root-dir set to the checkout, docs/**/*.md and README.md as inputs, 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 httpbin.org, example.com hosts, localhost, testserver and placeholder proxies, and a lychee.toml with accept codes, retries, timeout and user agent. Add .lycheecache to .gitignore and a scripts/docs-check that runs the strict build alone. Install lychee, run it twice to show the cache, and open a pull request listing every reported address grouped by file without fixing outbound links.",
  "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 changes `mkdocs.yml`, `scripts/build`, `.gitignore` and `docs/contributing.md`, fixes the Markdown references that were plain typos, and adds `.github/workflows/links.yml`, `.lycheeignore`, `lychee.toml` and `scripts/docs-check`. Its description has two sections: the warnings the first strict build raised and which ones were fixed, and lychee's cold and cached summaries with every reported outbound address under the file that contains it.

The `Test Suite` workflow runs `scripts/build` on the pull request across its Python matrix, so the strict build is checked five times before merge, and the new `links.yml` runs once because the pull request touches `docs/`. The run's record keeps both sandbox invocations of lychee and the strict build output, so a reviewer can compare the lists in the description with what the workflows show.

Before merging, a reviewer decides whether pull requests should block on a dead outbound link or only report, picks the schedule day, and goes through the outbound list to update or ignore each address. The site's content, theme and navigation are otherwise unchanged.

## Run it on every MkDocs repository without link checks

An organisation with several documentation sites 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 `mkdocs.yml`, so a site on an older MkDocs gets a pull request that raises the pin before adding `validation`, and a site that already builds with `--strict` gets only the lychee layer.

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 redirect target where it is clear and lists the rest" turns the report into a change once a maintainer adds the label. The issue the workflow opens 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?

The two layers fail in different ways and both need a real run to tune: the strict build turns on checks the site has never passed, so the first attempt reports references that have been quietly broken for years, and lychee against a docs tree full of sample hosts reports `httpbin.org` on every quickstart line until the ignore file is right. The agent runs both in its own sandbox and arrives with the lists, not with a workflow that goes red on its first schedule.

Every command stays with the run, from the strict build to the second lychee pass, so a maintainer who reviews from a phone can still read what each check found. The same prompt runs across every MkDocs site an organisation keeps, each in its own sandbox and with its own pull request.

## Frequently asked questions

### Why both MkDocs validation and lychee?

MkDocs resolves relative links and anchors between its own pages and images at build time and never fetches an address. Lychee fetches outbound `https` links and does not understand the nav. The strict build catches a renamed page or a missing image before merge; lychee catches someone else's server moving, which happens on no schedule of yours.

### Will --strict break the existing build?

On the first run it fails on whatever the site already has wrong, which is the point of running it in the sandbox first. The pull request fixes plain typos and lists the rest; a team can merge with `--strict` on only once that list is empty, or leave `validation` at `warn` without `--strict` until it is.

### What goes in .lycheeignore?

Hosts the docs use as examples rather than destinations: `httpbin.org` and `www.example.com` in the quickstart, `localhost` and `testserver` in the testing pages, and placeholder proxies. Each pattern has a comment with the reason, and the sandbox run shows what each excludes.

### Does lychee check the API reference generated by mkautodoc?

It checks the Markdown sources, and `docs/api.md` holds `mkautodoc` directives whose links come from docstrings at build time. A team that wants those checked can point lychee at the built `site/` directory in the same job after `mkdocs build`.

## More MkDocs jobs

- [Add llms.txt to a MkDocs Site](https://getrush.ai/run/add-llms-txt/mkdocs/)
- [Add Mermaid Diagrams to a MkDocs Site](https://getrush.ai/run/add-mermaid-diagrams/mkdocs/)
- [Add PDF Export to a MkDocs Site](https://getrush.ai/run/add-pdf-export/mkdocs/)

## The same job on other stacks

- [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/)
- [Check for Broken Links in a Starlight Docs Site](https://getrush.ai/run/add-link-checking/starlight/)

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