# Add Versioned Docs to a Docusaurus Site

Yes. An agent snapshots your current docs as a version with docs:version, adds the version dropdown and the Next label, checks the build and links, and opens a PR.

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

## What the agent does

The agent reads the site's configuration and its scripts first. In a site laid out like testing-library/testing-library-docs, `package.json` depends on `@docusaurus/core` and `@docusaurus/preset-classic` at `^2.0.1` (resolved to 2.0.1 in `package-lock.json`) with React 16 and `@docusaurus/remark-plugin-npm2yarn`, and its scripts include `start`, `build` and `serve`, a `docusaurus` passthrough, and three leftovers from the v1 CLI, `version` (`docusaurus-version`), `rename-version` and `write-translations`, whose binaries v2 does not ship. `docusaurus.config.js` configures the classic preset with docs at `./docs`, `sidebarPath: './sidebars.js'`, an `editUrl` into the repository, `showLastUpdateAuthor` and `showLastUpdateTime`, `onBrokenLinks: 'log'`, a navbar with two `type: 'doc'` items pointing at `introduction` and `recipes`, footer links into `docs/...`, Algolia search with an `appId` and `indexName`, and a blog. `netlify.toml` builds with `npm install; npm run format; npm run build` and holds a long list of redirects, including a fallback from `/docs/*` into `/docs/dom-testing-library/`.

Versioning in Docusaurus 2 is one command and a handful of files. `npm run docusaurus docs:version <name>` copies `docs/` into `versioned_docs/version-<name>/`, writes `versioned_sidebars/version-<name>-sidebars.json` from the current `sidebars.js`, and appends the name to `versions.json`. From then on the snapshot is the latest version at `/docs`, and the working `docs/` folder is labelled `Next` and served at `/docs/next/`. The agent runs that command with the name from the prompt (a library release number, typically), adds `{ type: 'docsVersionDropdown', position: 'right' }` to the navbar, and leaves the two `type: 'doc'` items alone, since they resolve against whichever version the reader is in. The three dead v1 scripts come out of `package.json`, and the `version` one in particular, because npm runs a script with that name during `npm version` and it would fail there.

Then it checks what the snapshot did to links. `onBrokenLinks: 'log'` means a broken link never fails the build, so the agent runs `npm run build` and reads the log for the versioned pages: absolute links written as `/docs/...` keep pointing at the latest version, which is what a reader on that version expects, while a relative link inside `versioned_docs` stays within the snapshot. It sets the docs plugin's `editCurrentVersion: true` so the edit button on an old version opens the current file rather than the frozen copy, since the site's `editUrl` is there to collect fixes. Footer links to `docs/...` keep working because `/docs` still exists; the Netlify redirects are untouched because they match paths, not versions. It serves the build with `npm run serve`, opens the dropdown, the `Next` version and one versioned page in the sandbox's browser, and keeps the screenshots.

Two things the agent writes into the pull request rather than changing: Algolia DocSearch is configured in `themeConfig.algolia` but indexed by a crawler outside the repository, and a versioned site wants that crawler to record the version so the search box can filter by it; and the docs say to keep the number of versions below ten, archiving older ones as links to immutable deploys, so the team should decide a retention rule before the second snapshot. It runs `npm run format` (Prettier over `.js`, `.json` and `.mdx`, as the Netlify build does) and opens the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add versioned docs to this Docusaurus 2 site. Read package.json, package-lock.json for the resolved Docusaurus version, docusaurus.config.js, sidebars.js, netlify.toml and the docs directory first. Run npm run docusaurus docs:version with the version name I give you, commit versioned_docs, versioned_sidebars and versions.json, add a docsVersionDropdown item to the navbar, set editCurrentVersion on the docs plugin, and remove any v1 CLI scripts such as docusaurus-version from package.json. Run npm run build and read the broken-link log for the versioned pages; fix relative links that escaped the snapshot. Serve the build and open the dropdown, the Next version and one versioned page in the browser. Run npm run format. Open a pull request that lists the files the snapshot created, every link the build logged, and the two decisions left to the team: how the search index should record the version and how many versions to keep.",
  "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` and `package.json` and adds `versions.json`, `versioned_sidebars/version-<name>-sidebars.json` and the whole `versioned_docs/version-<name>/` tree. Its description lists the files the snapshot created with their count, quotes the broken-link lines the build logged and what was done about each, and attaches the three screenshots from the served build.

A reviewer checks the version name, confirms the `Next` label is what the team wants for the working docs (the `versions` option on the plugin can relabel it), reads the search note and decides who updates the crawler configuration, and settles the retention rule. The tree under `versioned_docs` is a copy and needs no line-by-line review.

From the next change onward, an edit to `docs/` lands on `Next` only, and a fix meant for the released version is made under `versioned_docs`, which the pull request spells out so contributors know where to edit.

## Run it on every new major release

A handler on your server receives GitHub's release webhook for the library the docs describe, and for a release that changes the major or minor version sends one `POST /o/{org}/sessions` with this body, the docs repository in `resources`, the new version name written into `input`, and a `request_id` that is a UUID v5 of the release id, so a redelivered webhook returns the run already started rather than snapshotting twice. The handler is what writes the version into the prompt; a trigger fills in no placeholder.

A team that documents several libraries from one site uses the same handler for each, and the pull request for each release carries that library's version name. A release that only patches the current version starts no run, because the `Next` docs already describe it.

## Why run it on Rush?

Versioning is one command and a long tail of checks: the broken links the build only logs, the edit button that opens a frozen copy, the dropdown that needs a navbar entry, the `npm version` lifecycle script that would run a binary that no longer exists, and the search index that needs to know about versions. The agent runs the build and serves it in its own sandbox, reads the log, opens the pages in a browser and keeps the screenshots with the pull request.

A reviewer reads a list of the created files, the logged links and the two open decisions rather than a diff of several hundred copied Markdown files. A team with several sites starts the same request across all of them at once.

## Frequently asked questions

### Which version is served at /docs after this?

The snapshot. Docusaurus serves the latest entry in `versions.json` at `/docs` and the working `docs/` folder at `/docs/next/` with the label `Next`. The `lastVersion` option on the docs plugin changes which one `/docs` means, and `versions` relabels either.

### Does the blog get versioned?

No. Only the docs plugin has versions; the blog and standalone pages are unaffected. The dropdown appears only on docs pages.

### How big does the build get?

Every version is built, so the build time and the output grow with each snapshot. That is why the docs recommend fewer than ten versions and `onlyIncludeVersions` to deploy a subset, and why the pull request asks the team for a retention rule.

### What about search?

The Algolia configuration in `themeConfig` stays as it is. For the search box to filter by version, the DocSearch crawler needs to record the version of each page, which is set in the crawler configuration rather than in this repository; the pull request names it as the one step outside the diff.

## More Docusaurus jobs

- [Review Pull Requests on a Docusaurus Docs Site](https://getrush.ai/run/review-pull-requests/docusaurus/)
- [Upgrade a Docusaurus 2 Site to Docusaurus 3](https://getrush.ai/run/upgrade-docusaurus/docusaurus/)
- [Add a Build Check for a Docusaurus Site on Every Pull Request](https://getrush.ai/run/add-docs-build-check/docusaurus/)

## The same job on other stacks

- [Add a Version Menu to a Hugo Docsy Site](https://getrush.ai/run/add-versioned-docs/hugo/)
- [Add Versioned Documentation to an MkDocs Site With mike](https://getrush.ai/run/add-versioned-docs/mkdocs/)
- [Add Versioned Docs to a Starlight Site](https://getrush.ai/run/add-versioned-docs/starlight/)

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