managing-docs-versions

Managing Documentation Versions

The Golem docs site at 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/...:

   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/...:

   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:

   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:

   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:

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

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/:

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

# 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