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 with this body:
{
"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"
}
]
}- 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 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add Versioned Docs to a VitePress Site (VitePress)
- Add Versioned Docs to a Docusaurus Site (Docusaurus)
- Add a Version Menu to a Hugo Docsy Site (Hugo)