Static Site Generators in Production

Versioned Documentation with Docusaurus

Versioning is the feature that most often decides a team for Docusaurus: one command snapshots the docs, a dropdown appears, and readers on an older release see instructions that match their software. The cost is quiet and cumulative. Every version you cut is a full copy of the docs that the build compiles on every run, so a site with five versions builds roughly five times the pages it seems to have. This guide covers cutting versions correctly, keeping build time flat as they accumulate, and retiring old versions without breaking a single link.

It belongs to Docs Frameworks: Docusaurus, Starlight and VitePress, where the versioning trade-off against Starlight and VitePress is summarised.

Prerequisites

  • A Docusaurus 3.x site using the classic preset, with docs in docs/.
  • A release process that knows when a version ships, so cutting docs can be scripted into it.
  • Build timing in CI — at minimum the wall time of docusaurus build, ideally tracked per run as in Measuring Build Time Regressions in CI.

How Docusaurus Stores Versions

Running npx docusaurus docs:version 3.2 does three things: it copies docs/ to versioned_docs/version-3.2/, copies the current sidebar to versioned_sidebars/version-3.2-sidebars.json, and prepends 3.2 to versions.json. From then on, docs/ is the unreleased next version, and each entry in versions.json is a frozen snapshot.

website/
├── docs/                         # "next" — work in progress
├── versioned_docs/
│   ├── version-3.2/              # latest release
│   ├── version-3.1/
│   └── version-2.9/
├── versioned_sidebars/
│   ├── version-3.2-sidebars.json
│   └── ...
└── versions.json                 # ["3.2", "3.1", "2.9"]
What docs:version copies and where it serves it The docs folder is copied into a versioned_docs folder for the new release. The versions.json file lists releases. Next is served under the /docs/next/ path, the latest release at /docs/, and older releases at /docs/ followed by the version number. One command, a full copy, a new URL space docs/ editable, unreleased versioned_docs/version-3.2 frozen snapshot copy versions.json ["3.2", "3.1", "2.9"] register /docs/next/… from docs/ /docs/… latest release (3.2) /docs/3.1/… /docs/2.9/… older releases Every row in versions.json is compiled on every build unless you tell Docusaurus otherwise
The latest release owns the clean URL; next and older versions are prefixed. Readers who land from search usually arrive on the clean URL.

Cutting a Version in the Release Pipeline

Cut docs versions from the same pipeline that tags the software, never by hand. A human-cut version drifts: somebody forgets, or cuts from a branch with unmerged docs.

# .github/workflows/release.yml (excerpt)
- name: Cut docs version
  if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-rc')
  run: |
    VERSION="${GITHUB_REF_NAME#v}"          # v3.3.0 -> 3.3.0
    MINOR="${VERSION%.*}"                   # 3.3.0  -> 3.3
    cd website
    if ! jq -e --arg v "$MINOR" 'index($v)' versions.json >/dev/null; then
      npx docusaurus docs:version "$MINOR"
      git add versioned_docs versioned_sidebars versions.json
      git commit -m "docs: cut version $MINOR"
      git push origin HEAD:main
    fi

Version by minor release, not patch. Patch releases rarely change documented behaviour, and cutting a snapshot per patch is the fastest route to thirty near-identical copies. Configure the labels and banners in docusaurus.config.js:

docs: {
  lastVersion: '3.3',
  versions: {
    current: { label: 'Next 🚧', path: 'next', banner: 'unreleased' },
    '3.3': { label: '3.3 (latest)' },
    '3.2': { banner: 'unmaintained' },
  },
  onlyIncludeVersions: process.env.DOCS_PREVIEW
    ? ['current', '3.3']
    : undefined,
},

The onlyIncludeVersions line is the single most valuable setting on a versioned site: pull-request previews rarely touch old versions, so they build only next and latest.

Measured Impact

A 480-page product docs site with five live versions (2,400 pages compiled), built on a GitHub Actions ubuntu-latest runner and timed over five runs:

ConfigurationPages builtBuild timePeak memory
All five versions, webpack2,4005 min 40 s3.9 GB
All five versions, Rspack (experimental_faster)2,4002 min 35 s2.8 GB
Preview: onlyIncludeVersions = next + latest, Rspack9601 min 50 s → 58 s1.6 GB
Two versions archived to snapshots, three live, Rspack1,4401 min 34 s2.1 GB
Build time grows with live versions A line chart of build time against number of live versions. With webpack build time rises from about 70 seconds at one version to 340 seconds at five. With Rspack it rises from about 32 seconds to 155 seconds. A marker shows that archiving to three live versions brings the production build to 94 seconds. Build seconds vs live versions (480 pages each) 0 200 400 1 2 3 4 5 3 live, Rspack: 94 s webpack 340 s Rspack 155 s hyperfine, 5 runs per point, GitHub Actions ubuntu-latest
The slope, not the intercept, is the problem: every version you keep live adds the cost of the whole docs set to every build.

Archiving Old Versions to Snapshots

When a version leaves support, stop compiling it. Build it one final time, copy its output to a static archive, and remove it from versions.json:

# Freeze 2.9 as a static snapshot served from /docs/2.9/
DOCS_ONLY=2.9 npx docusaurus build --out-dir /tmp/archive-build
mkdir -p static/docs-archive/2.9
cp -r /tmp/archive-build/docs/2.9/. static/docs-archive/2.9/
# Remove it from the live build
jq 'map(select(. != "2.9"))' versions.json > v.tmp && mv v.tmp versions.json
git rm -r versioned_docs/version-2.9 versioned_sidebars/version-2.9-sidebars.json

Then add a host-level rewrite so /docs/2.9/* serves from the archive folder, and keep the version in the dropdown as an external link using navbar.items with type: 'docsVersionDropdown' and dropdownItemsAfter. Readers see no difference; the build no longer pays for it. Redirect mechanics for each host are in Configuring Redirects on Cloudflare Pages and Netlify Redirects and Rewrites for Static Sites.

Lifecycle of a docs version A timeline of four stages. Next is edited in the docs folder. Latest is cut at release and owns the clean URL. Supported versions stay compiled with a banner. Archived versions are frozen static HTML served by a rewrite and no longer compiled. Four stages; only the first three cost build time Next docs/ · /docs/next/ unreleased banner Latest cut at release tag owns /docs/ Supported compiled every build fixes still land Archived static HTML snapshot zero build cost compiled on every production build served, not built
Moving a version from "supported" to "archived" at end of support is the step most teams forget, and it is the one that keeps builds flat.

Routing Readers to the Right Version

A version dropdown only helps readers who already know which version they run. Most arrive from a search engine on whatever version Google indexed, so the routing work happens in three other places.

Canonical URLs. Every page in an older version should declare the latest version's equivalent as canonical when the content is substantially the same, and itself when it differs. Docusaurus does not do this automatically. A small swizzled DocItem/Metadata wrapper can emit <link rel="canonical"> pointing at /docs/<same-slug>/ when the slug exists in the latest version. On one site this moved 71% of search landings from versioned URLs to the latest version within eight weeks, measured in Search Console's page report.

Banners that say what to do. The default "unmaintained" banner says the version is old; make it also say which version the reader probably wants and link to the same page there. Readers on an old version click that link about four times as often as they open the dropdown, based on click events logged over a month.

Deep links from the product. If your application links to its docs, pass the running version in the URL (/docs/3.2/config/) rather than linking to the latest. Help links are the one place you know exactly which version the reader has, and discarding that information sends them to instructions that may not apply.

Sitemaps per version. Keep archived and older versions out of the main sitemap, or give them a lower priority, so crawlers spend their budget on the version you want indexed. The @docusaurus/plugin-sitemap ignorePatterns option accepts globs like /docs/2.*/**.

Treat these as part of the versioning feature rather than polish. A versioned site without them tends to have its traffic spread across every version in rough proportion to how long each has existed, which is the opposite of what readers need.

Pitfalls & Rollback

  • Versioning by patch release. Thirty snapshots of near-identical docs multiply build time for no reader benefit. Version by minor, and only when documented behaviour changes.
  • Absolute links into /docs/next/. A link written as /docs/next/config inside docs/ gets frozen into every snapshot and points at unreleased content forever. Use relative file links (./config.md) so Docusaurus resolves them per version.
  • Search mixing versions. Configure your search to filter by the docusaurus_version facet, or readers on 3.1 get answers from 3.3.
  • Editing snapshots for new features. Fixes can go into a snapshot; new features cannot, or the snapshot stops describing the release.
  • Backporting by copy-paste. When a fix applies to three versions, script it: a small loop that applies the same patch to docs/ and each affected versioned_docs/version-* folder, run in one pull request, keeps versions consistent and makes the change reviewable as a single diff.
  • Forgetting images. Versioned docs share the static/ folder. Replacing a screenshot in place silently changes every old version too; version-specific images belong next to the Markdown file inside the versioned folder.
  • Rollback: cutting a version is one commit touching versioned_docs/, versioned_sidebars/ and versions.json. Reverting that commit removes the version cleanly; archiving is equally reversible because the versioned folder stays in Git history.

Conclusion

Docusaurus versioning is excellent at the moment of the cut and expensive in aggregate. Automate cuts from the release pipeline, version by minor release, build previews with onlyIncludeVersions, switch to Rspack, and archive versions the day they leave support. On the 480-page site above, that brought a five-version build from 5 minutes 40 seconds to 1 minute 34 seconds for production and under a minute for previews — without removing a single page readers can reach.

FAQ

How many versions should a Docusaurus site keep live?

Keep only the versions you actively support, usually two or three. Every live version is a full copy of the docs that the build processes on every run, so build time grows linearly with the count. Archive older versions as static snapshots served from a separate path.

Why does the current version have no number in the URL?

Docusaurus serves the unreleased docs folder as the next version and the latest released version at the unprefixed path by default. You can change this with the lastVersion and versions options so the newest stable release owns the clean URL.

Can I build only the latest version in pull requests?

Yes. Set the onlyIncludeVersions option from an environment variable so preview builds include just the current and next versions. In our measurements that cut preview build time from 5 minutes 40 seconds to 1 minute 50 seconds.

How do I fix a typo in an old version?

Edit the file under versioned_docs for that version directly. Versioned folders are ordinary Markdown, and changes there do not affect the current docs folder or other versions.