# Add a Strict Docs Build Check to MkDocs Docs

Yes. An agent raises MkDocs link validation to warnings, fixes the anchors the build only reports as info today, makes the CI build run with --strict and opens a PR.

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

## What the agent does

The agent reads what the build already checks before it tightens anything. In a project like encode/httpx, `mkdocs.yml` uses the Material theme with a `custom_dir` of `docs/overrides`, a `nav` of twenty-three pages under Introduction, QuickStart, Advanced, Guides, API Reference and Community, the `admonition`, `codehilite` and `mkautodoc` extensions and one `extra_css` file, and no `validation` block. `requirements.txt` pins `mkdocs==1.6.1`, `mkautodoc==0.2.0` and `mkdocs-material==9.6.18` next to the test tools; `scripts/build` runs `python -m build`, `twine check dist/*` and `mkdocs build`; `scripts/publish` runs `twine upload` and `mkdocs gh-deploy --force` on a tag; and `.github/workflows/test-suite.yml` runs `scripts/install`, `scripts/check`, `scripts/build`, `scripts/test` and `scripts/coverage` on five Python versions, so the docs are built on every pull request already, without `--strict`.

Running `mkdocs build --strict` in the sandbox with those pinned versions passes, and that is the finding: MkDocs 1.6 validates anchors, but its default level for `links.anchors` and `links.unrecognized_links` is `info`, which `--strict` ignores. The same build prints seven INFO lines. `async.md` links to `../advanced/transports#asgitransport`, which MkDocs does not recognise as a document link and suggests `advanced/transports.md#asgitransport`; `compatibility.md` points at `advanced/clients.md#client-instances`, `environment_variables.md` at `advanced/proxies.md#http-proxying` and `third_party_packages.md` at `advanced/authentication.md#customizing-authentication`, and none of those anchors exist; `advanced/clients.md` links to `#client-instances` and `#merging-of-parameters` on itself and `advanced/proxies.md` to `#routing`, which are not on those pages either. The agent reads the headings to see what each link meant: `clients.md` has `Why use a Client?`, `Usage` and `Merging of configuration`, `proxies.md` has `HTTP Proxies` and `Proxy mechanisms`, `authentication.md` has `Custom authentication schemes`, and `transports.md` is checked for the `ASGITransport` anchor before the suggested form is used.

With the links read in context, the agent fixes each one to the heading it was written for, `#merging-of-parameters` to `#merging-of-configuration` and `#customizing-authentication` to `#custom-authentication-schemes` among them, and writes the one that is ambiguous, `#client-instances`, as a question in the pull request with its best guess applied. Then it adds a `validation` block to `mkdocs.yml` with `links.anchors`, `links.unrecognized_links` and `links.absolute_links` at `warn`, leaving `nav` validation at its defaults, and changes `scripts/build` to `mkdocs build --strict`, so the next broken anchor fails the `Build package & docs` step of the test suite on the pull request that introduces it. `scripts/docs`, which serves the site locally, is left alone so a writer sees the warning without being stopped.

To prove the order of events, the agent runs the build three times in its sandbox with the pinned versions: once as the repository stands, to keep the seven INFO lines; once with only the `validation` block, where the same seven become warnings and `--strict` fails, which is the check working; and once with the fixes, where `--strict` passes with no warnings. It runs `scripts/build` whole, so the package build and `twine check` still pass beside the docs, serves `site/` and clicks the repaired links in its own browser to confirm each lands on the right heading.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Make this project's MkDocs build fail on broken links and anchors. Read mkdocs.yml, requirements.txt, every script under scripts/ and the workflows under .github/workflows first, and run mkdocs build --strict with the pinned versions to see what passes today and what the build only reports as info. Add a validation block that raises anchors, unrecognized links and absolute links to warn, then fix every link the stricter build reports by reading the headings each one was meant to reach; where a link is ambiguous, apply your best reading and ask in the pull request. Switch the CI build script to mkdocs build --strict and leave the local serve script as it is. Show the build before the change, with the validation block but before the fixes, and after the fixes, run the whole build script, open the repaired links in a browser, and open a pull request with the commands and their output.",
  "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` and the six Markdown files that held the seven links. Its description shows the three builds side by side, the before state with INFO lines, the failing middle state and the clean strict build, and lists each link as file, old target, new target and the heading it now reaches, with the one ambiguous case marked.

A reviewer settles the ambiguous anchor, decides whether `nav` validation should be raised too, and checks that `scripts/docs` still serves without `--strict`. After merging, a pull request that renames a heading without updating its links fails the test suite's build step with the file and anchor named.

## Run it on every MkDocs project in the terminal

A developer with `mkdocs serve` running sends this body from their own machine with the repository in `resources` and reads the pull request from the console when the webhook on their API key reports the run. A team with several documented packages sends one request per repository, each with a `request_id` that is a UUID v5 of the repository's full name, so a script run twice returns the runs already started rather than a second set of pull requests.

Each run reads its own build: a project whose docs are built by a dedicated workflow gets the flag there, one on an MkDocs older than 1.6 gets an upgrade note instead of an anchors setting, and one that already runs strict gets only the validation levels it lacks.

## Why run it on Rush?

The build is green and still has broken anchors, which is the kind of fact nobody discovers by reading the workflow file. The agent runs the pinned toolchain in its own sandbox, finds the seven links the build only whispers about, reads the headings to repair them properly, and shows the check catching them before it shows the check passing, with every command and its output kept in the run's record.

It also changes the build where the project builds, the `scripts/build` file the test suite and the publish step both call, rather than adding a parallel workflow. Several packages with the same scripts layout get the same change at once, each with its own list of repaired links.

## Frequently asked questions

### Why does --strict pass today if anchors are broken?

MkDocs 1.6 added anchor validation, but its default level is `info`, and `--strict` turns only warnings into errors. The `validation` block in the pull request raises `links.anchors` and two related checks to `warn`, which the documentation describes as the level meant for strict builds.

### Will this slow down or break the publish step?

No. `scripts/publish` runs `mkdocs gh-deploy --force` on a tag and does not call `scripts/build`; the strict build runs earlier, in the test suite, where a broken link is cheap to fix. The agent runs the whole `scripts/build` to show the package build and `twine check` are unaffected.

### Does it check links to other sites?

No. MkDocs validation covers documents and anchors inside the site; external URLs need a separate link checker, which the pull request mentions as a follow-up rather than adding.

### What if a heading was renamed on purpose?

Then the links to it were already broken, and the fix is the same: point them at the current heading. The agent reads each link in its sentence before choosing, and flags the one it cannot settle from context rather than guessing silently.

## More MkDocs jobs

- [Add Giscus Comments to a MkDocs Material Site](https://getrush.ai/run/add-giscus-comments/mkdocs/)
- [Add i18n to a MkDocs Site](https://getrush.ai/run/add-i18n/mkdocs/)
- [Show Last Updated Dates on MkDocs Pages](https://getrush.ai/run/add-last-updated-dates/mkdocs/)

## The same job on other stacks

- [Fail CI on Sphinx Warnings and Broken Links for a Python Library](https://getrush.ai/run/add-docs-build-check/python/)
- [Add a Docs Build Check for a Sphinx Site on Every Pull Request](https://getrush.ai/run/add-docs-build-check/sphinx/)
- [Add a Build Check for a VitePress Docs Site on Every Pull Request](https://getrush.ai/run/add-docs-build-check/vitepress/)

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