# Managing Docs Versions

> Managing Docs Versions is an Agent Skill for documents published in the golemcloud/golem repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Cutting a new docs version, promoting next to a release, and managing versioned documentation content under docs/src/content/. Use when releasing a new Golem version, backporting docs fixes to an older release, renaming a docs version, or adding/removing a version from the version selector.

- Skill name: `managing-docs-versions`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/golemcloud/golem/blob/HEAD/.agents/skills/managing-docs-versions/SKILL.md
- Repository: golemcloud/golem (1,605 GitHub stars when collected)

## SKILL.md

# Managing Documentation Versions

The Golem docs site at [learn.golem.cloud](https://learn.golem.cloud) is versioned. Every page lives under `docs/src/content/<version>/`, the site exposes a version selector in the navbar, and unreleased docs are written under the special `next` slug.

This skill covers the recurring maintenance workflows: cutting a release, backporting fixes, renaming a version, registering/retiring versions, and the safety rules for editing versioned content.

## How versioning is wired

- **Registry of versions**: `docs/src/lib/versions.ts` — single source of truth for slugs, labels, statuses (`current`, `unreleased`, `legacy`), and `DEFAULT_VERSION`.
- **Routing**: `docs/src/app/[version]/[[...mdxPath]]/page.tsx` + `docs/src/app/[version]/layout.tsx`. Each version gets its own sidebar via `getPageMap("/<slug>")`.
- **Root redirect**: `docs/src/app/page.tsx` → `/${DEFAULT_VERSION}`.
- **Legacy URL redirects**: `docs/src/proxy.ts` redirects any un-prefixed path (e.g. `/quickstart`) to `/${DEFAULT_VERSION}/quickstart` (308).
- **Selector + banner**: `docs/src/components/version-selector.tsx`, `docs/src/components/version-banner.tsx`.
- **Per-version search**: `docs/src/components/versioned-search.tsx` passes a Pagefind `version` filter; the layout tags content with `data-pagefind-filter="version:<slug>"`.
- **Link tooling**: `docs/scripts/version-tool.ts` (prefix / clone / rename / check).
- **Auto-generated content** (always targets `next` by default; freeze older versions by hand):
  - REST API MDX: `docs/openapi/gen-openapi.ts` (driven by `cargo make generate-docs-openapi`)
  - How-To Guides MDX: `docs/skills/sync-skills.ts` (driven by `cargo make generate-docs-skills`)

## Core invariant: every internal MDX link must be version-prefixed

Inside any `docs/src/content/<version>/**/*.mdx` file:

- Doc links must start with `/<version>/` (e.g., `/v1.5/quickstart`). The version selector's smart-fallback only works if links don't cross versions implicitly.
- Public-asset links (`/images/...`, `/favicon.ico`, `/icon.svg`) stay **un-prefixed** — they live in `docs/public/`.

`bun run scripts/version-tool.ts check` (run from `docs/`) enforces this and exits non-zero if any prose link is missing its version prefix.

## Workflow: cut a new release (e.g., promote `next` → `v1.6`)

Run from the `docs/` directory unless noted otherwise.

1. **Promote `next` to the new release slug.** This renames the directory and rewrites every `/next/...` link inside it to `/v1.6/...`:

   ```bash
   bun run scripts/version-tool.ts rename next v1.6
   ```

2. **Re-seed `next` from the new release.** This clones the directory and rewrites every `/v1.6/...` link back to `/next/...`:

   ```bash
   bun run scripts/version-tool.ts clone v1.6 next
   ```

3. **Update the registry** in `docs/src/lib/versions.ts`:
   - Add `{ slug: "v1.6", label: "v1.6", status: "current" }`.
   - Demote the previous `current` entry to `status: "legacy"`.
   - Bump `DEFAULT_VERSION` to `"v1.6"`.
   - Keep `{ slug: "next", status: "unreleased" }` as the last entry.

4. **Regenerate the auto-generated content for `next`.** The in-tree OpenAPI spec and `golem-skills/skills/` are always the source of truth for `next`:

   ```bash
   cargo make generate-docs-openapi   # writes docs/src/content/next/rest-api/
   cargo make generate-docs-skills    # writes docs/src/content/next/how-to-guides/
   ```

5. **Verify**:

   ```bash
   bun run scripts/version-tool.ts check    # no unversioned links anywhere
   bun run build:check                      # lint + format + typecheck + link-check
   bun run build                            # full Next build + Pagefind index
   ```

   Confirm in the build summary that Pagefind reports `Indexed 1 filter` (the `version` filter). Each version slug must be present in `public/_pagefind/filter/*.pf_filter` — `zcat < public/_pagefind/filter/*.pf_filter | strings | grep -E "v1\\.5|v1\\.6|next"` should print all of them.

6. **Manually smoke-test in dev** (`bun run dev`): visit `/`, the selector, the banner on `/next`, and a few cross-version page switches.

7. **Commit** everything (the renamed directory, the cloned directory, the registry change, and the regenerated `next/rest-api/` + `next/how-to-guides/` + `next/how-to-guides.mdx`).

## Workflow: backport a fix to an already-released version

Older versions are **frozen snapshots**. They are not regenerated by CI. To make a small fix:

1. Edit the MDX file directly under `docs/src/content/v1.5/...`.
2. Keep any internal links version-prefixed (`/v1.5/...`).
3. Run `bun run scripts/version-tool.ts check v1.5` and `bun run build:check`.

For REST API or How-To Guides fixes specifically, the generators support `--version <slug>` if you really need to re-run them against an older version's content:

```bash
bun run openapi/gen-openapi.ts --version v1.5
bun run skills/sync-skills.ts --local .. --version v1.5
```

But this only makes sense if the in-tree `openapi/golem-service.yaml` or `golem-skills/skills/` still match that release. In practice, hand-edit the frozen MDX instead.

## Workflow: rename a version

```bash
bun run scripts/version-tool.ts rename <oldSlug> <newSlug>
```

- Renames `docs/src/content/<oldSlug>/` → `docs/src/content/<newSlug>/`.
- Rewrites every `/<oldSlug>/...` link inside the renamed tree to `/<newSlug>/...`.
- Does **not** touch links in other versions' directories — you do not normally want cross-version links.

After renaming, update `docs/src/lib/versions.ts` and (if needed) `DEFAULT_VERSION`.

## Workflow: retire a legacy version

1. Decide whether to keep the content reachable. If yes, just flip its registry entry to `status: "legacy"` so the banner appears.
2. To remove it entirely:
   - `git rm -r docs/src/content/<slug>`
   - Remove the entry from `docs/src/lib/versions.ts`.
   - Old URLs under `/<slug>/...` will then hit the catch-all `notFound()`. Optionally add a redirect in `docs/next.config.mjs` to send them to `/${DEFAULT_VERSION}`.

## Workflow: add a fresh page to an existing version

1. Create `docs/src/content/<version>/path/to/page.mdx`.
2. Add it to the nearest `_meta.js` for ordering/title.
3. All internal links inside it must be `/<version>/...`. New images go in `docs/public/images/` and are referenced as `/images/...`.

## Editing rules and gotchas

- **Never edit** `docs/src/content/next/rest-api/` or `docs/src/content/next/how-to-guides/` by hand. CI drift checks (`cargo make check-docs-openapi`, `cargo make check-docs-skills`) will reject any PR that diverges from the regenerated output. Edit the sources (`openapi/golem-service.yaml`, `golem-skills/skills/`) and regenerate.
- **Public assets stay unprefixed.** A link like `/v1.5/images/foo.png` is wrong and will 404. Image links should look like `![alt](/images/foo.png)`.
- **Cross-version links are not supported.** A page in `v1.5/` should not link to `/next/...` and vice versa. The selector handles switching between versions for the same logical page.
- **The version tool is idempotent.** Running `prefix` or `check` repeatedly is safe; running `rename` or `clone` into an existing destination errors out (by design).
- **Dev server caching.** Turbopack occasionally fails to compile `/v1.5` (the index) on a cold start with stale state. If it happens, `rm -rf .next` and restart `bun run dev`. Production builds (`bun run build`) are unaffected.

## Quick reference: version tool

Run from `docs/`:

```bash
# Confirm every absolute link inside a version is correctly prefixed
bun run scripts/version-tool.ts check [<version>]

# Initial-migration helper: prefix every absolute link inside a version
# with /<version> (only needed when a directory was populated without
# prefixes; new content should be written prefixed from the start).
bun run scripts/version-tool.ts prefix <version>

# Copy a version, rewriting links from /<source>/ to /<target>/
bun run scripts/version-tool.ts clone <source> <target>

# Move a version, rewriting links from /<old>/ to /<new>/
bun run scripts/version-tool.ts rename <old> <new>
```

## Pre-PR checks specific to this skill

After any version-management change:

```bash
# from docs/
bun run scripts/version-tool.ts check
bun run build:check
bun run build

# from the repo root
cargo make check-docs-openapi
cargo make check-docs-skills
```

---

Source: https://www.openparable.com/skill/documents/managing-docs-versions (OpenParable). Cite the canonical URL above.