skills.rest
golemcloud
golemcloudOFFICIAL
Explore all skills by this author →
WebsiteGitHub

managing-docs-versions

Manages versioned documentation releases, backports, and link rewriting for Golem docs.

1.5k|212|Updated Nov 24, 2023
Search Tags:#release#NextJS#mdx#Documentation#Versioning#link-checking#backport
One-click install
npx skills add https://github.com/golemcloud/golem --skill managing-docs-versions
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: managing-docs-versions
Source: https://github.com/golemcloud/golem/tree/main/.agents/skills/managing-docs-versions
Command: npx skills add https://github.com/golemcloud/golem --skill managing-docs-versions

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Maintaining multiple frozen documentation versions alongside a live next branch is error-prone: links break, version registries drift, and redirects get lost. This Skill codifies the exact commands and file locations for cutting releases, backporting fixes, and renaming versions in the Golem docs site.

Core Features & Use Cases

  • Release Cutting: Rename next to vX.Y, clone it back, update versions.ts, and regenerate OpenAPI and How-To sources with cargo make targets.
  • Link Checking and Rewriting: Run version-tool.ts check to validate version-prefixed MDX links and use rename/clone to rewrite links inside moved trees.
  • Backports and Retirement: Edit frozen MDX directly for backports, and add explicit redirects in next.config.mjs when retiring content.
  • Use Case: When releasing Golem v1.5, follow the documented sequence to freeze next as v1.5, regenerate live sources, verify Pagefind indexing per version, and smoke-test version switching.

Quick Start

Ask the assistant to cut a new docs release from next to v1.5 and verify the build and link checks pass.

Frequently Asked Questions about managing-docs-versions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I cut a new documentation release from next to a versioned snapshot?▼

Run version-tool.ts rename next vX.Y, then clone vX.Y back to next, update versions.ts with the new lifecycle statuses, and regenerate OpenAPI and How-To sources with cargo make. Finish by running the link check, build, and smoke tests.

How do I backport a docs fix to an already released version?▼

Edit the frozen MDX directly in that version's directory, preserving its link prefix, then run version-tool.ts check vX.Y and bun run build:check from the docs directory. Only use generator --version flags when current sources genuinely represent that release.

What does the docs link checker actually validate?▼

The check validates registered version prefixes from VERSIONS in Markdown link destinations and quoted JSX href/to attributes. It skips fenced code, public paths, relative links, and dynamic href expressions, and it does not verify that destinations exist.

Does removing a docs version automatically redirect its old URLs?▼

No. Removing content or registry entries does not create redirects. You must add an explicit redirect in docs/next.config.mjs, check ordering against src/proxy.ts, and test both index and nested old URLs.

Why should generated docs files not be edited by hand?▼

Generated outputs like next/rest-api/ and How-To pages are regenerated from source by cargo make targets, so manual edits are overwritten. Change the source inputs and regenerate instead.

Related Skills

Explore More Software Engineering Skills→
ophidiariumophidiarium
5

mintlify

Build Mintlify documentation sites by authoring MDX pages and configuring docs.json navigation.

Official
Intermediate
ThalesGroupThalesGroup
19

docs-publish-github-pages

Inspect and patch GitHub Pages docs publishing workflows.

Official
Advanced
hffmnnjhffmnnj
39

api-docs

Generate API reference documentation from OpenAPI specs and GraphQL schemas.

Community
Advanced
leaderiopleaderiop
7

Documentation Docusaurus

Enforce Docusaurus coding standards across MDX/Markdown content, configuration, and navigation.

Community
Intermediate