# Add a Version Menu to a Hugo Docsy Site

Yes. An agent configures Docsy's version menu and archived-version banner in your Hugo site's config, adds a test for the built menu, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-versioned-docs/hugo/). 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 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`

```json
{
  "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"
    }
  ]
}
```

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 `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.

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

- [Review Pull Requests on a Hugo Theme](https://getrush.ai/run/review-pull-requests/hugo/)
- [Add a GitHub Pages Deploy Workflow to a Hugo Site](https://getrush.ai/run/add-deploy-workflow/hugo/)
- [Add Giscus Comments to a Hugo Blog](https://getrush.ai/run/add-giscus-comments/hugo/)

## The same job on other stacks

- [Add Versioned Documentation to an MkDocs Site With mike](https://getrush.ai/run/add-versioned-docs/mkdocs/)
- [Add Versioned Docs to a Starlight Site](https://getrush.ai/run/add-versioned-docs/starlight/)
- [Add Versioned Docs to a VitePress Site](https://getrush.ai/run/add-versioned-docs/vitepress/)

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