All jobs

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

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

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

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

The same job on other stacks

Keep reading