[TODO] Archive old doc versions

[Tobbe]

Provide links to archived versions of old docs instead of rebuilding them all the time.
Follow the guide here https://www.spectrocloud.com/blog/when-docs-and-a-dinosaur-git-along-enabling-versioning-in-docusaurus

[anajafizadeh]

I'll do it

[Tobbe]

Awesome! Please do 🙏

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.

[lisa-assistant]

Implementation Plan

Context

Docusaurus rebuilds all versioned docs on every build run — currently that includes 14 versions (0.x through 8.x), which makes CI/CD significantly slower. The goal is to serve archived versions from a static snapshot rather than rebuilding them every time.

Approach: Per-Version Banner + noIndex for Old Versions

Docusaurus's docs plugin supports per-version configuration in docusaurus.config.ts's versions object. We can:

1. Add all old versions to the versions block with banner: 'unmaintained' and noIndex: true — this tells Docusaurus they're archived and search engines won't index them.
2. Use the onlyIncludeVersions option in development (via an env-var guard) so the dev server only rebuilds current + 3.x docs.

Files to Change

docs/docusaurus.config.ts — Expand the docs.versions block:

versions: {
  current: {
    label: 'Canary',
    path: 'canary',
    banner: 'unreleased',
  },
  '3.1': { label: '3.1', banner: 'none' },     // latest stable — no banner
  '3.0': { label: '3.0', banner: 'unmaintained', noIndex: true },
  '2.8': { label: '2.8', banner: 'unmaintained', noIndex: true },
  // ... all 2.x and earlier
  '8.x': { label: 'Redwood 8.x', banner: 'unmaintained', noIndex: true },
},
// Only build recent versions in dev/CI unless FULL_BUILD is set
...(process.env.FULL_BUILD ? {} : { onlyIncludeVersions: ['current', '3.1', '3.0'] }),

Why onlyIncludeVersions matters: This is the key perf win. With FULL_BUILD=1 yarn build for production deploys, all versions are built. For PR previews and yarn start, only 3 versions build — taking the build from O(14) to O(3).

Edge Cases / Considerations

• Version dropdown UX — The dropdown still shows all versions (because versions.json is unchanged). Users can still navigate to old docs; they just get an "unmaintained" banner.
• Production deploy — CI needs FULL_BUILD=1 set for the job that pushes to cedarjs.com. Add this env var to the deploy workflow.
• Broken anchor errors — The onBrokenAnchors default is warn in Docusaurus v3+. If you want to suppress errors from old versioned docs during partial builds, add onBrokenLinks: 'warn' scoped inside the versions config (or leave as-is since old versions won't be built in CI PR previews).
• Alternative (hosted archive): A more drastic option is to pre-build old versions once, push the static HTML to a CDN (e.g. an S3 bucket or GitHub Pages sub-path), then remove them from versions.json entirely and add a custom redirect/link in the dropdown to the hosted archive. This is the approach from the Spectrocloud blog. It's more work upfront but entirely eliminates rebuild cost. The onlyIncludeVersions approach above is simpler and reversible — good first step.

[lisa-assistant]

Self-fix confidence: 6/10

The docusaurus.config.ts changes are mechanical and well-documented in Docusaurus's versioning API. The 4-point deduction is for:

1. Production deploy coordination — the CI/CD pipeline (Netlify netlify.toml or equivalent) needs a FULL_BUILD=1 env var; I'd need access to the deployment config to verify the right place to set it.
2. All-version build testing — verifying that FULL_BUILD=1 yarn build still produces zero broken links across all 14 versions requires a full local build run (~10+ minutes) that I can't do in the current environment.
3. Version dropdown behavior — need to test that the version dropdown still lists all versions even when onlyIncludeVersions is active (it should, but the UX interaction between the two settings needs verification).