Menu
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.
| name | managing-docs-versions |
| description | 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. |
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.
docs/src/lib/versions.ts — single source of truth for slugs, labels, statuses (current, unreleased, legacy), and DEFAULT_VERSION.docs/src/app/[version]/[[...mdxPath]]/page.tsx + docs/src/app/[version]/layout.tsx. Each version gets its own sidebar via getPageMap("/<slug>").docs/src/app/page.tsx → /${DEFAULT_VERSION}.docs/src/proxy.ts redirects any un-prefixed path (e.g. /quickstart) to /${DEFAULT_VERSION}/quickstart (308).docs/src/components/version-selector.tsx, docs/src/components/version-banner.tsx.docs/src/components/versioned-search.tsx passes a Pagefind version filter; the layout tags content with data-pagefind-filter="version:<slug>".docs/scripts/version-tool.ts (prefix / clone / rename / check).next by default; freeze older versions by hand):
docs/openapi/gen-openapi.ts (driven by cargo make generate-docs-openapi)docs/skills/sync-skills.ts (driven by cargo make generate-docs-skills)Inside any docs/src/content/<version>/**/*.mdx file:
/<version>/ (e.g., /v1.5/quickstart). The version selector's smart-fallback only works if links don't cross versions implicitly./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.
next → v1.6)Run from the docs/ directory unless noted otherwise.
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
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
Update the registry in docs/src/lib/versions.ts:
{ slug: "v1.6", label: "v1.6", status: "current" }.current entry to status: "legacy".DEFAULT_VERSION to "v1.6".{ slug: "next", status: "unreleased" } as the last entry.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/
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.
Manually smoke-test in dev (bun run dev): visit /, the selector, the banner on /next, and a few cross-version page switches.
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).
Older versions are frozen snapshots. They are not regenerated by CI. To make a small fix:
docs/src/content/v1.5/..../v1.5/...).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.
bun run scripts/version-tool.ts rename <oldSlug> <newSlug>
docs/src/content/<oldSlug>/ → docs/src/content/<newSlug>/./<oldSlug>/... link inside the renamed tree to /<newSlug>/....After renaming, update docs/src/lib/versions.ts and (if needed) DEFAULT_VERSION.
status: "legacy" so the banner appears.git rm -r docs/src/content/<slug>docs/src/lib/versions.ts./<slug>/... will then hit the catch-all notFound(). Optionally add a redirect in docs/next.config.mjs to send them to /${DEFAULT_VERSION}.docs/src/content/<version>/path/to/page.mdx._meta.js for ordering/title./<version>/.... New images go in docs/public/images/ and are referenced as /images/....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./v1.5/images/foo.png is wrong and will 404. Image links should look like .v1.5/ should not link to /next/... and vice versa. The selector handles switching between versions for the same logical page.prefix or check repeatedly is safe; running rename or clone into an existing destination errors out (by design)./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.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>
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
Developing, testing, and running Golem skill tests with the skill test harness. Use when creating new skills, writing scenario YAML files, running skill tests locally, or debugging skill test failures.
Adding or modifying HTTP REST API endpoints in Golem services. Use when creating new endpoints, changing existing API routes, or updating request/response types for the Golem REST API.
Final checks before submitting a pull request. Use when preparing to create a PR, to ensure formatting, linting, and the correct tests have been run.
Adding a new component or agent templates to an existing Golem application. Use when adding a second component, adding agent templates like human-in-the-loop or snapshotting to an existing component, or converting a single-component app to multi-component.
Defining environment variables for Golem agents in `golem.yaml` (`env`, `envDefaults`, `secretDefaults`) or via CLI. Use when adding, setting, or overriding env vars on a component, agent, template, preset, or environment, or when wiring template substitution and merge modes.
Adding initial files to Golem agent filesystems via the `files:` section in `golem.yaml`. Use when provisioning local or remote files into an agent's virtual filesystem, setting read-only / read-write permissions, or configuring file mounts at the component, agent, template, or preset level.