# Add Redirects for Moved Pages to a Docusaurus Site

Yes. An agent reads your docs' git history and host redirects, adds @docusaurus/plugin-client-redirects with one rule per moved page, builds and opens a PR.

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

## What the agent does

The agent reads where the site's redirects live today before adding any. In a site like testing-library/testing-library-docs, `docusaurus.config.js` runs `@docusaurus/preset-classic` on Docusaurus 2 with `onBrokenLinks: 'log'`, an empty `plugins: []` and no redirect plugin, while `netlify.toml` carries thirty `[[redirects]]` rules: old domains to the new one, shortcuts like `/discord` and `/new-rtl`, `/support` to `/help`, one-off moves such as `/docs/guide-which-query` to `/docs/queries/about#priority` and `/docs/dom-testing-library/api-queries` to `/docs/queries/about`, and a catch-all `/docs/*` to `/docs/dom-testing-library/:splat` for a reorganisation. Those rules work only on Netlify. A preview from `npm run serve`, a mirror, or a move to another host loses all of them, and nothing in the build checks that their targets still exist.

Then it asks git what moved. `git log --diff-filter=R -M --name-status -- 'docs/*'` on the full history shows the big `.md` to `.mdx` rename of 2020, which changed no routes, and the moves that did: `docs/using-fake-timers.mdx` to `docs/guides-using-fake-timers.mdx` in January 2021 and `docs/ecosystem-user-event.mdx` to `docs/user-event/v13.mdx` in November 2023. `--diff-filter=D` lists the pages deleted outright: `api-helpers.mdx`, `api-queries.mdx` and `guide-which-query.mdx` in the same 2021 commit, `example-react-redux.md` in 2020, and most recently `docs/ecosystem-jest-native.mdx`, removed in May 2026 with its sidebar entry. The agent then reads each surviving file's front matter, because in Docusaurus the route comes from the `id` field, not the file name: `guides-using-fake-timers.mdx` still declares `id: using-fake-timers`, so `/docs/using-fake-timers` never broke and the Netlify rule for `/docs/guide-using-fake-timers` still lands, and the `user-event/api-*.mdx` files declare ids like `clipboard` and `keyboard`, so their routes carry no `api-` prefix. From that it builds the list of old routes that need a rule, and notices that `/docs/ecosystem-jest-native` has none anywhere: the page was deleted, the catch-all sends it to a path under `dom-testing-library/` that does not exist either, and the right target is the React Native example page that the deletion commit edited.

It adds `@docusaurus/plugin-client-redirects` at the same major version as the preset and registers it in `plugins` with a `redirects` array that mirrors every page-level Netlify rule, one object per old route with `from` and `to`, plus the jest-native entry, and leaves the domain, shortcut and catch-all rules in `netlify.toml`, since the plugin writes an HTML page per `from` and cannot express a wildcard or an external target. The plugin is inactive under `docusaurus start` and runs only in a production build, where it emits a small HTML file at each old path that sends the browser to the new one, so the site keeps its Netlify rules for server-side speed and gains the same moves on any host. The rules that include a fragment, like `#priority`, keep it in `to`, which the generated page preserves.

To check it, the agent runs `npm ci` and `npm run build` with the pinned 2.x packages, reads the build log, which on this site already reports one broken link from `api-configuration` to `queries/byrole#hidden`, and confirms the plugin wrote `build/docs/guide-which-query/index.html` and `build/docs/ecosystem-jest-native/index.html` beside the real pages. It serves `build/` and opens three old addresses in its own browser to watch each land on its new page, with the fragment intact where there is one. Finally it points `onBrokenLinks` at `'throw'` in a scratch build to list every link the site still breaks, and reports that list in the pull request without changing the setting, since that decision belongs to the maintainers.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add client-side redirects for the pages this Docusaurus site has moved or deleted. Read docusaurus.config.js, sidebars.js and any host configuration such as netlify.toml or vercel.json that already holds redirects. Use git log with --diff-filter=R and --diff-filter=D over the docs directory on the full history to find every renamed and deleted page, and read each surviving page's front matter because the route comes from its id, not its file name. Install @docusaurus/plugin-client-redirects at the site's Docusaurus major version and register it with one rule per old route, mirroring the page-level host rules and adding any deleted page that has no rule, pointing it at the page that replaced it. Leave wildcard, domain and external rules where they are and say why. Build the site, confirm the generated redirect files exist, open a few old addresses in a browser, run a scratch build with onBrokenLinks set to throw to list remaining broken links without changing the setting, 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 `docusaurus.config.js`, `package.json` and the lockfile, and nothing under `docs/`. Its description lists every redirect as old route, new route and the commit that moved or deleted the page, names the host rules it mirrored and the ones it left in place with the reason, quotes one generated redirect file, and ends with the broken-link list from the scratch build.

A reviewer checks the target chosen for each deleted page, since those are editorial choices rather than renames, and decides whether to raise `onBrokenLinks` now that the list is short. After merging, the next production build writes the redirect pages, an old bookmark to a deleted ecosystem page lands on its replacement on any host, and a future rename gets its rule in the same array in the same pull request.

## Run it on every Linear issue labelled docs

A docs team that tracks site work in Linear adds an automation to the Project with a `linear` trigger on `linear.issue.labeled`, the label `docs`, with the automation set to read only. Each labelled issue starts a read-only run that reads the history and the host rules and posts, as a comment on the issue, the old routes it found with and without a rule and the target it would choose for each. Only a change made by a member of the Rush org fires the trigger, and that comment is the whole result, because an automation's runs push nothing.

When the targets are agreed, a handler on the team's own server sends this body with the issue's URL added to `resources`, which puts the issue text in front of the agent through the team's Linear connection, and a `request_id` that is a UUID v5 of the issue id, so a second delivery of the same event returns the run already started instead of opening a second pull request.

## Why run it on Rush?

The list of broken addresses is not in the tree; it is in the history and in a host file nobody reads after deploy day, and matching the two needs each page's front matter, because the route is the `id`. The agent runs those git queries, reads every id, builds the site with its pinned packages in its own sandbox and opens the old addresses in a real browser, with every command and its output kept in the run's record, so the pull request can show the redirect landing rather than describe it.

It also respects the site's own setup instead of replacing it: Netlify keeps the rules only Netlify can express, the plugin takes the page moves that should survive a change of host, and the broken-link policy stays the maintainers' call with the evidence attached. Several Docusaurus sites with several histories get several pull requests, each with that site's own list.

## Frequently asked questions

### We already have redirects on Netlify. Why add the plugin?

The Netlify rules work only on Netlify, so a local `npm run serve`, a preview on another host or a future migration loses them, and nothing in the build checks their targets. The plugin writes a redirect page into the build output for each old route, so the moves travel with the site; the agent mirrors the page-level rules and leaves the wildcard, domain and external ones where only Netlify can handle them.

### Why does the route not match the file name?

Docusaurus builds a doc's route from the `id` in its front matter, falling back to the file name only when there is none. The agent reads every front matter for that reason, which is how it tells a rename that changed a route from one that did not, like a file renamed under the same `id`.

### Does the redirect work in development?

No. The plugin's documentation says it is inactive under the dev server and works on the production build output, so the agent checks it with `npm run build` and `npm run serve` and opens the old addresses there. Server-side rules on your host remain the faster path where you have them.

### What about pages that were deleted rather than moved?

The agent reads the deleting commit, which usually edits the pages that referred to the deleted one, and points the rule at the page that took over, marking those entries in the pull request as choices rather than renames. A reviewer can point one elsewhere before merging.

### Will it change onBrokenLinks?

No. It runs a scratch build with the setting at `throw` to list every link the site still breaks and puts that list in the pull request, but leaves the committed setting as it is. Raising it is the maintainers' decision, and the list makes it an informed one.

## More Docusaurus jobs

- [Add a Typo Check to a Docusaurus Site in CI](https://getrush.ai/run/add-typo-check/docusaurus/)
- [Add Versioned Docs to a Docusaurus Site](https://getrush.ai/run/add-versioned-docs/docusaurus/)
- [Review Pull Requests on a Docusaurus Docs Site](https://getrush.ai/run/review-pull-requests/docusaurus/)

## The same job on other stacks

- [Add Redirects for Moved Pages to an mdBook](https://getrush.ai/run/add-redirects/mdbook/)
- [Add Redirects for Moved Pages to a MkDocs Site](https://getrush.ai/run/add-redirects/mkdocs/)
- [Add Redirects for Moved Pages to Sphinx Docs](https://getrush.ai/run/add-redirects/sphinx/)

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