All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading