All jobs

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 RushOpens 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 with this body:

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

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

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

The same job on other stacks

Keep reading