# Add Versioned Docs to a VitePress Site

Yes. An agent keeps one VitePress site per major on its own branch, adds a version menu and an archive banner, and opens a pull request per branch with build output.

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

## What the agent does

The agent reads how the docs are built and deployed before it decides how to version them. In a monorepo like vuejs/pinia, the docs are a workspace package, `packages/docs`, with `vitepress` 1.6.4, `vitepress-plugin-llms` and `typedoc-vitepress-theme` as dependencies and scripts `docs`, `docs:build` and `docs:api`, the last running `run-typedoc.mjs` to generate the API pages from the library's types. `.vitepress/config/index.ts` spreads a `shared.ts` config and defines locales: `root` and `zh` built from this repository, and `es`, `ko`, `pt`, `uk` and `ru` as links to sites other people deploy. `netlify.toml` builds with `pnpm run docs:build`, publishes `packages/docs/.vitepress/dist`, pins `NODE_VERSION = "24"` and skips builds through `scripts/docs-check.sh`, which exits zero unless `packages/docs/`, the vitepress entry in `pnpm-lock.yaml`, `netlify.toml` or a `docs`-prefixed commit message changed. `.github/workflows/ci.yml` lists `packages/docs/**` in its paths but runs only lint, type checks and tests, never a docs build.

The repository already versions by branch, and the docs lag that. `packages/pinia/package.json` is 4.1.0 on the default branch, `v4`, with `v3`, `v2` and `v1` branches beside it; the `v3` branch's `packages/pinia/package.json` is 3.0.4 and its `netlify.toml` is identical to the current one. Yet `en.ts` and `zh.ts` on `v4` still show a nav item `text: 'v3.x'` whose only entry is `v2.x` linking to `https://v2.pinia.vuejs.org`, and their changelog link points at `blob/v3/packages/pinia/CHANGELOG.md`. On the `v2` branch the same menu reads `v2.x` with an item `v3.x` pointing at `https://pinia.vuejs.org`, which is the pattern the project uses for an archived major: the menu names the version you are reading and links the others. So the work is to carry that pattern to the new major, give `v3` an archive site, and make the archive say it is one.

On `v4` the agent edits `en.ts` and `zh.ts` so the menu reads `v4.x` with items `v3.x` at `https://v3.pinia.vuejs.org` and `v2.x` at the existing `v2` address, and points both changelog links at `blob/v4`. To stop the menu drifting again, it reads the version from `packages/pinia/package.json` in `shared.ts` and derives the `vX.x` label from its major, so the next major changes the label by itself. On the `v3` branch it opens a second pull request with the mirror image, `v3.x` current and `v4.x` at `https://pinia.vuejs.org`, and adds an archive banner through the theme: `.vitepress/theme/index.ts` already wraps `DefaultTheme.Layout` with slots for the hero image, the aside and `doc-before`, and carries a commented-out `layout-top` slot, so the agent adds a small `VersionBanner.vue` in that slot that renders only when a `VITE_DOCS_ARCHIVED` build variable is set, saying which version these docs are for and linking to the current site. The banner's strings go in both locales, since `zh` is built from the same branch.

Then it builds both. It runs `pnpm install --frozen-lockfile` and `pnpm run docs:build` on each branch, which runs the typedoc step first, opens the output with `vitepress preview` in its browser, and checks the menu on the home page and on a `zh` page, the banner on the `v3` build and its absence on `v4`, and that `sitemap.xml` under `dist` still names `pinia.vuejs.org` on the current branch, because `shared.ts` hard-codes the sitemap `hostname` and the archive needs its own. It leaves `netlify.toml` alone on both branches, since the archive is a second Netlify site built from the `v3` branch with the same command, and the person who owns the Netlify account creates it; the pull request on `v3` lists the three settings that site needs, the branch, the `VITE_DOCS_ARCHIVED` variable and the `v3` subdomain, and the `v4` pull request says its `v3.x` link resolves only once that site exists.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Set up versioned docs for this VitePress site. Read the docs package, every file under .vitepress/config and .vitepress/theme, netlify.toml, the deploy-skip script and the CI workflow first, and read the library's package.json on the default branch and on each older major branch to learn which versions exist and how their docs differ. On the current branch make the version menu name the current major, derived from the library's package.json so it cannot drift, with one item per older major linking to that major's own site, and fix any changelog link that points at an older branch. On the most recent older branch open a second pull request that flips the menu to name that version and link the current site, and adds a banner in the theme's layout-top slot, shown only when an archive build variable is set, in every locale the branch builds. Run the docs build on both branches, open the output in the browser and check the menu, the banner and the sitemap hostname. Do not change the deploy config; list instead the settings a second deploy of the older branch needs. Open both pull requests with the build 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

Two pull requests. The one on the current branch changes `en.ts`, `zh.ts` and `shared.ts`: the version menu, the derived label and the changelog links. The one on the older major's branch changes the same menu the other way, adds `VersionBanner.vue` and the `layout-top` slot in `theme/index.ts`, and adds the banner strings per locale. Each description has the `docs:build` output, screenshots of the menu and of the banner from the browser, and the three settings the archive deploy needs; the full build logs and every page the agent opened are in the run's record.

A reviewer checks the links in the menu against the sites that exist today, since the `v3.x` entry on the current branch points at a site that goes live only when someone creates it, and checks that the banner is gated on the build variable so a preview deploy of the older branch does not show it by accident. The build output answers whether the typedoc step and both locales still render.

## Run it on every terminal hand-off

A maintainer who has just tagged a new major starts this from the terminal with this body and the repository in `resources`, and returns to the release notes. The run reads the real branches and the real config, so the menu follows the versioning the repository already practises rather than a scheme imported from another tool.

Send a `request_id`, a UUID, with the body so a retried start returns the run it already began. When the turn ends, the answer `GET /o/{org}/sessions/{id}` carries links both pull requests, and a follow-up to the same session can ask it to add a `robots` rule or a `noindex` meta tag to the archive build once the second site exists.

## Why run it on Rush?

Versioned docs are a pair of edits that have to agree across two branches and two locales, and the mistake is always the same: a menu that still names last year's major, or a link to a site nobody created. The agent reads every branch, builds both, opens the output in its own browser and attaches the pictures, so the reviewer sees the menu and the banner as a reader will rather than as a diff of config.

The same run fits any VitePress site that keeps a branch per major, whether it deploys to Netlify, Vercel or Pages: the agent changes the config and the theme, not the host, and lists what the host needs. Each repository gets a menu derived from its own package version, and every run keeps the full record of the builds that prove it.

## Frequently asked questions

### Does it deploy the archived version?

No. The archive is a second site built from the older branch by the same `docs:build` command, and creating that site needs the hosting account. The pull request on the older branch lists the branch, the build variable and the hostname it needs, and the current branch's link resolves once it exists.

### What about the translations hosted elsewhere?

Locales that are links to other people's sites, like the Spanish or Korean docs, stay as links; the agent cannot version a site it does not build. The locales built from the repository, here English and Chinese, get the menu and the banner strings.

### Will the version label need editing at the next major?

No. The label is derived from the library's `package.json` major in `shared.ts`, so it changes when the version does. The items for older majors are a list in the same file; adding the next archive is one line.

### Why a banner instead of a different theme colour on the archive?

A banner in the `layout-top` slot is text a reader and a search engine can read, says which version it is and links to the current one. It is gated on a build variable so previews and local builds of the older branch look normal unless that variable is set.

## More VitePress jobs

- [Add Author Pages to a VitePress Blog](https://getrush.ai/run/add-author-pages/vitepress/)
- [Add a Dark Mode Toggle to a VitePress Blog With a Custom Theme](https://getrush.ai/run/add-dark-mode/vitepress/)
- [Add Dependabot to a VitePress Site](https://getrush.ai/run/add-dependabot/vitepress/)

## The same job on other stacks

- [Add Versioned Docs to a Docusaurus Site](https://getrush.ai/run/add-versioned-docs/docusaurus/)
- [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/)

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