# Add Versioned Docs to a Starlight Site

Yes. An agent adds the starlight-versions plugin to your Starlight site, archives the current docs as the first version, builds both, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-versioned-docs/starlight/). 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 before it changes how it is organised. In a site like the `examples/basics` starter in withastro/starlight, `package.json` depends on `@astrojs/starlight` `^0.42.7`, `astro` `^7.2.10` and `sharp` `^0.35.3`, with `dev`, `start`, `build`, `preview` and `astro` scripts and no lockfile of its own, because the example lives inside a pnpm workspace. `astro.config.mjs` configures `starlight()` with the title `My Docs`, one GitHub `social` link and a sidebar of two groups: `Guides`, listing `guides/example` by slug, and `Reference`, which autogenerates from the `reference` directory. `src/content.config.ts` defines a single `docs` collection with `docsLoader()` and `docsSchema()`. The content is three pages: `src/content/docs/index.mdx` with `template: splash` and a `hero` whose image is `../../assets/houston.webp`, `guides/example.md` and `reference/example.md`.

The plugin is `starlight-versions`, whose current release 0.10.1 lists `@astrojs/starlight` `>=0.39.0` as its peer, which 0.42.7 satisfies. Its own documentation calls it opinionated and still early: it versions by folder, not by branch or tag. The agent adds it to `package.json`, imports `starlightVersions` in `astro.config.mjs` and registers it under `plugins` with `versions: [{ slug: '1.0', label: 'v1.0' }]` and `current: { label: 'Latest' }`, then adds a second collection to `src/content.config.ts`: `versions: defineCollection({ loader: docsVersionsLoader() })`, imported from `starlight-versions/loader`, which reads JSON or YAML files under `src/content/versions/`.

The archive is created by the build, not by hand. On the first `astro build` after the config change, the plugin notices that `1.0` has no directory yet and copies `src/content/docs/` into `src/content/docs/1.0/`, copies referenced assets into a `1.0` folder beside the originals and rewrites the relative links in the copies, and writes `src/content/versions/1.0.json` with that version's sidebar and the list of excluded slugs. The agent runs the build once in its sandbox, commits the generated directory and JSON file, and checks `dist/` for both `guides/example/index.html` and `1.0/guides/example/index.html`. The sidebar now has a group per version, the header gains the version switcher, and navigating between versions keeps the same page by default (`redirect: 'same-page'`), or goes to the version's root when `redirect: 'root'` is set.

Two choices need a human and the agent makes them visible rather than guessing. The `exclude` option takes globs relative to `src/content/docs/`, such as `internal/**`, for pages that should always show the latest content; the agent leaves it empty and lists the three pages so the reviewer can pick. And the splash `index.mdx` is archived too, so `/1.0/` has its own landing page; the agent notes that the `hero` image path in the copy was rewritten by the plugin and shows both pages in a screenshot from its browser. It also runs `astro build` a second time to confirm the archive is stable, that is, that a build on an existing `1.0` directory creates nothing new.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add versioned docs to this Starlight site with the starlight-versions plugin. Read package.json, astro.config.mjs, src/content.config.ts, tsconfig.json and every page under src/content/docs first. Install the plugin at a release whose peer range matches the installed @astrojs/starlight, register it in astro.config.mjs with the current docs archived as version 1.0 labelled v1.0 and the current version labelled Latest, and add the versions collection with docsVersionsLoader to src/content.config.ts. Run astro build once so the plugin archives the current pages, commit the generated version directory and the versions JSON, then build again to confirm nothing else is generated. Check that dist contains both the latest and the 1.0 copy of each page, open both in a browser, and open a pull request with the build output and the screenshots. Leave exclude empty but list the pages a reviewer might want excluded.",
  "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 `package.json` and the lockfile the repository uses, `astro.config.mjs` and `src/content.config.ts`, and adds `src/content/docs/1.0/` with a copy of every page, the archived assets beside the originals, and `src/content/versions/1.0.json`. Its description pastes the two `astro build` outputs, the list of files the first build generated, and screenshots of the latest and the `1.0` pages with the version switcher open.

A reviewer sees that the current docs still live in `src/content/docs/` and are untouched, that the archive is a plain copy they can read in the diff, and that the sidebar config for `1.0` is frozen in a JSON file rather than recomputed from `astro.config.mjs`. The run's record keeps every command, including the second build that proves the archive is idempotent.

Before merging, a reviewer decides the real slug and label for the first version, which pages go in `exclude`, and whether the switcher should land on the same page or the version root. From then on, cutting `2.0` is one entry in `versions` and one build.

## Run it on every docs site that needs a frozen version per release

A platform team with one Starlight site per product sends this body once per repository to `POST /o/{org}/sessions`, each with its own repository in `resources`, the version slug for that product in `input`, and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `astro.config.mjs`, so a site that already has a `plugins` array gets the new entry appended, and one with `locales` configured gets the archive created per locale, which the plugin handles by skipping version directories nested inside locale directories.

After that, each release can cut a version through an automation with a `github` trigger on `pull_request.closed.merged` and the prompt "if this merged pull request raises the version in package.json, add a version to starlight-versions in astro.config.mjs whose slug is that version, run astro build so the current docs are archived under it, commit the generated files and open a pull request; otherwise do nothing". The trigger adds the pull request after the prompt, and only work by an owner, member or collaborator fires it, so the docs for the version that just shipped are frozen the same day.

## Why run it on Rush?

Versioning docs by folder is simple to read and easy to get wrong by hand: a copied directory with stale relative image paths, or a sidebar that still points at the latest slugs, looks fine until a reader lands on it. The agent lets the plugin generate the archive, builds the site twice in its sandbox to show the archive is complete and stable, and opens both versions in a browser before anyone reviews the diff.

The build logs, the generated file list and the screenshots stay with the run and are quoted in the pull request. A team with several documentation sites runs the same change on each at once, each in its own sandbox, and gets one reviewable pull request per site.

## Frequently asked questions

### Does the plugin copy my docs into git?

Yes. starlight-versions uses folder-based versioning: the first build after the config change copies `src/content/docs/` into `src/content/docs/1.0/` and writes `src/content/versions/1.0.json`. The pull request commits those files so the archive is reviewed once and then stays put; later builds create nothing new, which the agent checks by building twice.

### What about images and other assets?

Assets the archived pages reference are copied into a `1.0` folder beside the originals, and the relative links inside the copied pages are rewritten to point at them. The splash page's `hero` image in this example is one such link, and the agent shows the archived landing page rendering with it.

### Can some pages always show the latest content?

Yes, through the plugin's `exclude` option, a list of globs relative to `src/content/docs/` such as `internal/**`. Excluded pages use the current content whichever version is selected. The agent leaves the list empty and names the candidates in the pull request rather than deciding for you.

### How do I add the next version later?

Add `{ slug: '2.0' }` at the front of the `versions` array and run a build; the plugin archives the then-current docs as `2.0` and you keep editing `src/content/docs/` as the latest. The pull request's description includes that step, and the automation above does it once a pull request that raises the version in `package.json` is merged.

### Will the build get slower?

Each archived version is built in full, so a site with three versions renders roughly three times the pages. The plugin's own guide calls that out as the cost of folder-based versioning, and the agent pastes the timing lines from both builds so the reviewer sees the difference on this site rather than an estimate.

## More Starlight jobs

- [Run an SEO Audit on a Starlight Site](https://getrush.ai/run/seo-audit/starlight/)
- [Add a Blog to a Starlight Docs Site](https://getrush.ai/run/add-blog/starlight/)
- [Add a GitHub Pages Deploy Workflow to a Starlight Docs Site](https://getrush.ai/run/add-deploy-workflow/starlight/)

## The same job on other stacks

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

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