What the agent does
The agent starts from the history, because the list of broken URLs is in the commits rather than in the current tree. In a site built like encode/httpx, mkdocs.yml sets site_url to https://www.python-httpx.org/, the Material theme with a custom_dir of docs/overrides and two colour schemes, a nav whose Advanced section is nine pages under docs/advanced/, the admonition, codehilite and mkautodoc Markdown extensions, and no plugins key at all. requirements.txt pins the documentation tooling, mkdocs==1.6.1, mkautodoc==0.2.0 and mkdocs-material==9.6.18, with a comment explaining that tooling is pinned on purpose. scripts/build runs mkdocs build after the package build, scripts/publish runs mkdocs gh-deploy --force on a tag, and .github/workflows/test-suite.yml runs scripts/build on every pull request, so a plugin that fails to load breaks the test suite rather than the deploy. Reading git log --diff-filter=D and the renames over docs/, the agent finds that the commit titled Docs restructuring. (#3049) from January 2024 removed docs/advanced.md and added the nine docs/advanced/*.md pages, so the published /advanced/ URL, linked from blog posts and answers written over several years, now has no page behind it; and that docs/third-party-packages.md was last touched in March 2021, after which the page lives at docs/third_party_packages.md, so /third-party-packages/ is gone too.
The plugin is mkdocs-redirects, maintained in the MkDocs organisation. Its README says the redirect_maps setting takes the old Markdown path as the key and the new Markdown path or an external URL as the value, that during mkdocs build it writes an HTML file at the old location which forwards to the new one, that with use_directory_urls on it writes old/index.html pointing at the new directory URL, and that it warns when a target does not exist, which strict: true would turn into a failure. The README also carries the warning that matters for this site: adding a plugins setting replaces the defaults, so search has to be listed explicitly or the Material search box disappears. The agent pins mkdocs-redirects==1.2.2 in requirements.txt, the release whose only requirement is mkdocs>=1.1.1; the later 1.2.3 declares a dependency on a different package and an upper bound of mkdocs<=1.6.1, and the pull request says why the earlier one was chosen for a site that pins its tooling.
mkdocs.yml gains a plugins list with search first and then redirects with a redirect_maps of advanced.md: advanced/clients.md and third-party-packages.md: third_party_packages.md. The first target is the opening page of the section the old page became, which the agent picks from the nav order rather than guessing; the old page's sections are now spread over nine files, and because the plugin redirects whole pages rather than anchors, the pull request lists the headings the old advanced.md had, from the commit that removed it, next to the page each one moved to, so a reader can decide whether a hand-written anchor map in docs/overrides is worth adding. The nine new pages keep their own URLs: advanced/index.html is a new file the plugin writes, and nothing in docs/advanced/ collides with it.
Then the agent builds. It installs requirements.txt in its sandbox, runs mkdocs build and checks site/advanced/index.html and site/third-party-packages/index.html exist and name the new paths, then serves site/ on a local port and opens /advanced/ in its own browser to see it land on the clients page. It runs scripts/build as the test suite does, so the package build and twine check are known to still pass with the extra plugin installed. It searches docs/ for links to the old paths and finds none, and notes in the pull request that docs/async.md links to ../advanced/transports#asgitransport with a parent path that resolves only by accident, which is outside this change.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add redirects for moved and renamed documentation pages to this MkDocs site. Read mkdocs.yml, requirements.txt, the scripts directory, the docs directory and .github/workflows first, then read the git history of docs/ for deleted and renamed Markdown files and list every published URL that no longer has a page. Add mkdocs-redirects to requirements.txt, pinned like the other documentation packages, and add a plugins list to mkdocs.yml that keeps search and configures redirect_maps from each old Markdown path to the page it became, choosing the first page of a section when one page was split. Build the site, confirm the redirect files exist at the old paths, serve it and open an old URL in the browser, and run the project's own build script. Do not change any content page. Open a pull request with the commands and output, and list the old page's headings next to the pages they moved to.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 and requirements.txt and nothing under docs/. Its description lists each old URL with the page it now forwards to and the commit that moved it, quotes the mkdocs build output showing the plugin loaded and wrote the redirect pages, and includes the table of the old page's headings against the new pages. The search plugin is listed explicitly, so a reviewer can see the site keeps its search box.
A reviewer checks whether advanced/clients.md is the right landing page or whether a short index page under docs/advanced/ would serve old links better, whether any other URL they know of from issues or blog posts belongs in the map, and whether strict: true should be turned on so a redirect to a page that later moves again fails the build. Merging changes nothing until the next scripts/publish on a tag runs mkdocs gh-deploy, which the pull request notes.
Run it on every pull request that moves a docs page
An automation in the Project that holds the site takes a github trigger on pull_request.opened and pull_request.synchronize. Its runs are read-only, so the saved prompt asks the run to diff the pull request's branch against the base, list every Markdown file under docs/ that was deleted or renamed, check whether redirect_maps already covers each old path, and comment on the pull request with the entries that are missing, written as the exact YAML lines to add. A pull request that moves nothing gets no comment.
For a one-time sweep across several sites, a script sends this body once per repository with a request_id that is a UUID v5 of the repository's full name, and the key's webhook_url reports each pull request URL in result.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Which URLs are broken is a question about the repository's history, and whether the redirects work is a question about the built site; neither is answered by reading mkdocs.yml. The agent reads the commits that removed and renamed pages, builds the site in its own sandbox with the plugin installed, opens the old URL in a browser and keeps every command and its output in the run's record, so the pull request shows the redirect landing where it should.
The change follows the site's own rules, read from its files: the plugin is pinned because the comment in requirements.txt says tooling is pinned, search stays because the plugin README says a plugins key replaces the defaults, and the targets come from the nav order. A documentation site that has been restructured three times gets one pull request that covers all three moves, each tied to its commit.
Frequently asked questions
Will adding a plugins list break anything else?
It would remove the built-in search if search were left out, which is why the pull request lists it first. The site had no plugins key before, so search was on by default; the plugin README calls this out, and the build output in the pull request shows both plugins loading.
Can it redirect an anchor on the old page to the right new page?
No. The plugin maps pages, so /advanced/#timeouts lands on the new page's top, not on the timeouts page. The pull request lists the old headings next to the pages they moved to; an anchor-level map would be a small script in docs/overrides, which the agent describes but does not add unasked.
How does it know which pages moved?
From the repository's history: deletions and renames under docs/, with the commit that made each one. For a page that was split, the agent reads the nav to find the section's first page and names the commit in the pull request so a reviewer can confirm the choice.
Does this change the deploy?
No. scripts/publish still runs mkdocs gh-deploy --force on a tag, and the redirect pages are part of the normal build output. The next release publishes them; until then nothing on the live site changes.
Why pin an older plugin release?
Because the site pins its documentation tooling and the newest release declares an upper bound on MkDocs and an extra dependency. The pinned release needs only mkdocs>=1.1.1, which the site's mkdocs==1.6.1 satisfies, and the pull request names both so the next person to upgrade MkDocs knows to revisit it.