Multi-Version Documentation — Complete Guide

Multi-version documentation supports multiple software versions simultaneously. Learn how to structure versioned docs, use branching strategies, automate version switching, and maintain legacy version content.

What You'll Learn

You will learn how to structure documentation for multiple software versions, how to implement version switching in your static site generator, and how to maintain documentation for legacy versions.

Why It Matters

Users of older software versions still need accurate documentation. Without multi-version support, users either see documentation for the wrong version or the documentation is removed entirely when a new version ships.

Real-World Use

The DodaTech tutorials platform maintains documentation for the current and previous major version of each product. A version dropdown lets users switch between v2.x and v1.x documentation.

flowchart LR
  A[Documentation Root] --> B[v2.0 Current]
  A --> C[v1.0 LTS]
  B --> D[Getting Started]
  B --> E[API Reference]
  C --> F[Getting Started]
  C --> G[API Reference]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Hugo Versioning with Branches

The simplest approach: use Git branches for each version.

# Main branch holds the latest version
git checkout main
# Create a branch for v1.0 documentation
git checkout -b docs/v1.0
# On the v1.0 branch, remove v2.0-specific content
git rm -r content/v2/
# On main, remove v1.0-specific content
git rm -r content/v1/

Deploy each branch separately:

# Deploy v1.0 docs from the docs/v1.0 branch
git checkout docs/v1.0
hugo --baseURL /docs/v1.0/

# Deploy latest docs from main
git checkout main
hugo --baseURL /docs/latest/

Hugo Version Dropdown

# hugo.yaml
params:
  versions:
    - version: "v2.0"
      url: /docs/v2.0/
      latest: true
    - version: "v1.0"
      url: /docs/v1.0/

In the theme, add a version dropdown:

<select id="version-selector" onchange="location = this.value;">
  <option value="/docs/v2.0/">v2.0 (latest)</option>
  <option value="/docs/v1.0/">v1.0 (LTS)</option>
</select>

Docusaurus Versioning

Docusaurus has built-in versioning:

# Create a new version
npm run docusaurus docs:version 2.0

# The previous version (1.0) is preserved automatically
# in the versioned_docs/ and versioned_sidebars/ directories

# Switch between versions
npm run docusaurus docs:version 1.0
npm run docusaurus docs:version 2.0

Expected output:

[INFO] Version 2.0 created.
[SUCCESS] Versioning is configured.

Version Labels and Banners

Add version labels to indicate when content applies to a specific version:

{{</* callout type="warning" */>}}
This feature is available in version 2.0 and later.
For version 1.0, see the [legacy API guide](/docs/v1.0/api/).
{{</* /callout */>}}

Common Mistakes

1. Keeping Too Many Versions

Supporting five versions dilutes maintenance effort. Support the current version and one previous version maximum.

2. No Clear Version Labeling

Readers must know which version they are viewing. Show the version in the URL, page title, and a banner.

3. Copying Content Across Versions

Duplicated content drifts apart. Use shared snippets or conditional includes for content that does not change between versions.

4. Forgetting to Archive Old Versions

Versions that are no longer supported should be clearly marked as archived. Move them to a separate subdomain or add a deprecation notice.

5. Not Redirecting Old URLs

When restructuring versions, set up redirects from old URLs to the versioned equivalents so existing bookmarks and search results work.

Practice Questions

1. What is the recommended number of documentation versions to support?

The current version and one previous version. More than that spreads maintenance too thin.

2. How do you implement version switching in Hugo?

Use separate branches for each version, deploy them to different base URLs, and add a dropdown in the theme.

3. How does Docusaurus handle versioning natively?

Docusaurus has a built-in docs:version command that snapshots the current docs and preserves old versions in versioned_docs.

4. Why should old versions be clearly labeled?

Readers need to know immediately if they are viewing documentation for an outdated version. Banners and URL paths provide this context.

5. Challenge: Set up versioning for a documentation project. Create a v1.0 and v2.0 version with different content, implement a version switcher dropdown, and add a deprecation banner for v1.0.

FAQ

Mini Project

Create a Hugo documentation project with two versions. Use branches or subdirectories for v1.0 and v2.0. Create a version switcher in the theme, add version labels to URLs, and include a deprecation banner for v1.0.

What's Next

With versioning in place, learn about Search Integration to make your documentation discoverable. Then explore Localization for Docs.