What the agent does
The agent reads the site configuration first, because in a site laid out like docsy/docsy-example most of the versioning support is already there and switched off. hugo.yaml sets params.version_menu: Releases, params.archived_version: false and params.version: 0.18.1-dev, with a comment noting that the menu appears only once at least one entry under params.versions exists, and there is none; it also sets mainBranchPreviewURL: https://main--goldydocs.netlify.app/, baseURL: https://example.docsy.dev, three languages with fa right to left, outputs that add print, RSS, redirects, markdown and LLMS formats, and the github.com/docsy/docsy/theme module import with a minimum Hugo of 0.160.1. package.json pins hugo-extended at 0.166.0 and tracks the Docsy version in its own version field, with scripts for build, test:site (node --test over tests/**/*.test.mjs), check:links through lychee, and _check:format through Prettier. netlify.toml builds build:preview for deploy previews and build:production on the main site. tests/site.test.mjs reads built pages from public/ and asserts on the language menu's markup, which is the pattern the new test follows. .cspell.yml lists the words the spell check allows.
The configuration change is a params.versions list and two parameters beside it. The list opens with a name entry that acts as a heading, then one entry per documentation set: the development docs built from main at the preview URL with kind: next, the current release at the production URL with kind: latest, and one entry per archived release branch the repository documents, each with its version and url, or a commented example entry when there is none yet. params.url_latest_version is set to the production URL so the archived banner has somewhere to point, and params.version_menu_pagelinks is set to true so each entry links to the same page in that version rather than its home page, with a comment on the trade-off: a page that does not exist in an older version gives a broken link. archived_version stays false on main. Docsy adds a dropdown-item-<kind> class per entry and labels latest and next, so no template override is needed and layouts/ is untouched.
An archived version is a branch, not a config switch on main, so the agent documents the branch steps rather than guessing at the team's release process: a release branch sets archived_version: true and version to its own number, keeps url_latest_version, and Netlify's branch deploy builds it at a predictable subdomain; the banner then appears on every page of that set with a link to the latest docs. This goes into README.md under a short heading, with the three keys and the branch-deploy context from netlify.toml. Any new word in the config, such as a release subdomain, is added to .cspell.yml so the spell check stays green.
The test is tests/version-menu.test.mjs, modelled on site.test.mjs: it reads public/index.html, finds the navbar's version menu by Docsy's td-navbar__version-menu wrapper, asserts the Releases title is present, asserts one dropdown item per configured entry with the latest and next classes on the right ones, and checks that the Persian home page carries the same menu. The agent runs npm run install:safe, npm run build, npm run test:site, npm run check:links:internal for the offline link pass and npm run _check:format in its sandbox, and reads the rendered menu out of public/index.html for the pull request description.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a version menu to this Hugo Docsy site. Read hugo.yaml, package.json, netlify.toml, tests/site.test.mjs, .cspell.yml and README.md first. Under params in hugo.yaml add a versions list: a name entry as a heading, the development docs from the main branch preview URL with kind next, the current release at the production baseURL with kind latest, and one entry per archived release branch whose name and deploy URL the repository documents in README.md or netlify.toml; if there is none, add a commented example entry. Set url_latest_version to the production URL and version_menu_pagelinks to true with a comment on the broken-link trade-off. Keep archived_version false on main and document in README.md how a release branch sets archived_version, version and url_latest_version so the banner appears on it. Add tests/version-menu.test.mjs in the style of tests/site.test.mjs that reads public/index.html and asserts the Releases menu, one item per entry, the latest and next classes, and the same menu on the Persian home page. Add any new words to .cspell.yml. Run npm run install:safe, npm run build, npm run test:site, npm run check:links:internal and npm run _check:format, and open a pull request with the rendered menu markup in its description.",
"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 hugo.yaml, adds tests/version-menu.test.mjs, adds a section to README.md and, if a new subdomain needed it, a word to .cspell.yml. Its description pastes the node --test output with the new assertions named, the rendered dropdown from public/index.html with each item and its class, and the offline lychee result showing no new broken internal links.
Before merging, a reviewer confirms the production and preview URLs are the ones the site actually deploys to, decides whether version_menu_pagelinks should stay on given which pages exist in older sets, and plans the first archived branch, since the banner only appears once a branch sets archived_version to true.
Run it on every release
A team that cuts a release branch for each version sends this body from its own server when the branch is created, each a POST /o/{org}/sessions with the repository in resources and a request_id that is a UUID v5 of the branch name, so a retried call returns the run already started. The prompt names the new branch and its deploy URL, and the run adds the entry to the versions list on main and opens the pull request that flips archived_version on the branch.
Once the menu exists, an automation on the Project with a github trigger on pull_request.opened and the prompt "if this pull request changes params.versions in hugo.yaml, build the site and comment with the rendered menu and any entry whose URL does not answer" starts one run per such pull request. The trigger adds the pull request after the prompt, and only work by an owner, member or collaborator fires it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Docsy's versioning is a handful of parameters whose names are easy to misspell and whose effect is only visible in a built site: a wrong key leaves the menu hidden with no error. The agent reads the theme's parameter names, builds the site with the pinned Hugo and reads the rendered navbar back out of public/ before claiming the menu is there.
The build, the test run and the rendered markup stay with the run, so a reviewer sees the dropdown without checking out the branch. The same request runs across every Docsy site a team maintains, each in its own sandbox with its own Hugo install.
Frequently asked questions
Why is the menu not showing even though version_menu is set?
Because version_menu is only the dropdown's title. Docsy renders the menu when params.versions has at least one entry, and the example site has the title and the archived_version flag but no list. Adding the list is what makes the menu appear.
Where do the old versions actually live?
Each one is a branch built and hosted separately, for example a Netlify branch deploy, and the url on its entry points there. The config on main only lists them. The README section the agent adds says which three keys a release branch sets so the banner appears on that set.
Does version_menu_pagelinks break anything?
It can produce a link to a page that does not exist in an older version. The agent turns it on with a comment explaining that, because deep links are what readers usually want; a team that moves pages between releases can set it to false or put pagelinks: false on single entries.
Does it touch the theme's templates?
No. The menu, the latest and next labels and the archived banner are Docsy partials driven by the parameters, so layouts/ keeps only the two overrides the site already has. The agent changes configuration, a test and the README.
More Hugo jobs
The same job on other stacks
- Add Versioned Documentation to an MkDocs Site With mike (MkDocs)
- Add Versioned Docs to a Starlight Site (Starlight)
- Add Versioned Docs to a VitePress Site (VitePress)