Version Management

Maintaining documentation for multiple product versions is essential for supporting users across different releases. Doom provides comprehensive version management capabilities built into the CLI and configuration system.

Understanding Versions

Doom treats versions as separate builds of your documentation, each accessible at a unique URL path. This allows users to access documentation specific to their installed product version.

Version URL Structure

With versioned builds, your documentation is accessible at:

https://docs.example.com/{base}/{version}/

For example:

https://docs.example.com/product-docs/4.0/
https://docs.example.com/product-docs/4.1/
https://docs.example.com/product-docs/master/

Unversioned Builds

For single-version documentation:

https://docs.example.com/{base}/

No version prefix in the URL path.

Building Versions

Use the -v flag with the doom build command:

doom build -v <version>

Version Types

Release Versions
Branch Versions
Unversioned
Unversioned with Label

Semantic version numbers for stable releases:

doom build -v 4.0
doom build -v 4.1.0
doom build -v 3.9.2

Output: dist/{base}/{version}/
URL: {base}/4.0/

Development or branch-specific builds:

doom build -v master
doom build -v develop
doom build -v feature-xyz

Output: dist/{base}/{version}/
URL: {base}/master/

Single-version documentation without URL versioning:

doom build -v unversioned

Output: dist/{base}/
URL: {base}/ (no version)

Show version in UI but not in URLs:

doom build -v unversioned-4.0

Output: dist/{base}/
URL: {base}/
UI: Displays “v4.0” in navbar

Version Strategy

Semantic Versioning

Align documentation versions with your product releases:

# Major.Minor versioning
doom build -v 4.0
doom build -v 4.1
doom build -v 5.0

# Full semantic versioning
doom build -v 4.1.0
doom build -v 4.1.1

Most projects use Major.Minor versioning (4.0, 4.1) for documentation, reserving patch versions for product releases.

Branch-Based Versioning

For continuous documentation:

# Map branches to documentation versions
if [[ $BRANCH == "release-"* ]]; then
  VERSION=${BRANCH#release-}  # release-4.0 → 4.0
elif [[ $BRANCH == "main" ]]; then
  VERSION="master"
fi

doom build -v $VERSION

Git-Based Automation

Automate version detection from Git:

build-from-git.sh

#!/bin/bash

# Get current branch
BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Determine version from branch name
if [[ $BRANCH =~ ^release-([0-9]+\.[0-9]+)$ ]]; then
  VERSION="${BASH_REMATCH[1]}"
elif [[ $BRANCH == "main" ]]; then
  VERSION="master"
else
  VERSION="unversioned"
fi

echo "Building documentation version: $VERSION"
doom build -v $VERSION

Managing Multiple Versions

Directory Structure

After building multiple versions:

dist/
└── product-docs/          # base path
    ├── 4.0/
    │   ├── index.html
    │   ├── guide/
    │   └── api/
    ├── 4.1/
    │   ├── index.html
    │   ├── guide/
    │   └── api/
    ├── master/
    │   ├── index.html
    │   ├── guide/
    │   └── api/
    ├── index.html         # Root redirect
    ├── versions.yaml      # Version list
    └── overrides.yaml     # Config overrides

Version List Configuration

Create versions.yaml to define available versions:

versions.yaml

- '4.1'    # Latest version first
- '4.0'
- '3.9'
- 'master' # Development version

This powers the version selector dropdown in your documentation.

List versions in descending order, with the latest/recommended version first.

Root Redirect Page

Create a redirect to the latest version:

dist/product-docs/index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Redirecting to Documentation</title>
    <meta http-equiv="refresh" content="0; url=/product-docs/4.1">
    <script>
      window.location.href = '/product-docs/4.1';
    </script>
  </head>
  <body>
    <p>
      If you are not redirected automatically, 
      <a href="/product-docs/4.1">click here to go to the latest documentation</a>.
    </p>
  </body>
</html>

Automated Version Builds

GitHub Actions

.github/workflows/docs.yml

name: Build Documentation

on:
  push:
    branches:
      - 'release-*'
      - 'main'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install
      
      - name: Determine version
        id: version
        run: |
          BRANCH=${GITHUB_REF#refs/heads/}
          if [[ $BRANCH =~ ^release-([0-9]+\.[0-9]+)$ ]]; then
            echo "version=${BASH_REMATCH[1]}" >> $GITHUB_OUTPUT
          elif [[ $BRANCH == "main" ]]; then
            echo "version=master" >> $GITHUB_OUTPUT
          else
            echo "version=unversioned" >> $GITHUB_OUTPUT
          fi
      
      - name: Build documentation
        run: doom build -v ${{ steps.version.outputs.version }}
      
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: docs-${{ steps.version.outputs.version }}
          path: dist/

GitLab CI

.gitlab-ci.yml

stages:
  - build
  - deploy

variables:
  DOCS_VERSION: $CI_COMMIT_REF_NAME

build:docs:
  stage: build
  image: node:20
  script:
    - npm install
    # Transform branch name to version
    - |
      if [[ $CI_COMMIT_REF_NAME =~ ^release-([0-9.]+)$ ]]; then
        export VERSION="${BASH_REMATCH[1]}"
      elif [ "$CI_COMMIT_REF_NAME" == "main" ]; then
        export VERSION="master"
      else
        export VERSION="unversioned"
      fi
    - echo "Building version $VERSION"
    - doom build -v $VERSION
  artifacts:
    paths:
      - dist/
    expire_in: 1 week
  only:
    - main
    - /^release-.*$/

Version-Specific Configuration

Per-Version Overrides

Create version-specific overrides.yaml files:

dist/product-docs/4.0/overrides.yaml

title:
  en: Product Docs v4.0
  zh: 产品文档 v4.0

dist/product-docs/4.1/overrides.yaml

title:
  en: Product Docs v4.1
  zh: 产品文档 v4.1

These override the base configuration per version.

Build-Time Version Variables

Pass version-specific configuration during build:

# Using environment variables
export DOCS_VERSION="4.0"
export DOCS_TITLE="Product v4.0 Documentation"
doom build -v 4.0

Access in your MDX files using custom components or build-time processing.

Version Switcher UI

The version switcher is automatically enabled when versions.yaml exists.

Customizing Version Labels

Add display names in versions.yaml:

- version: '4.1'
  label: 'v4.1 (Latest)'
- version: '4.0'
  label: 'v4.0 (Stable)'
- version: 'master'
  label: 'Development'

Version switcher appearance is controlled by your theme configuration.

Cross-Version Linking

When linking between versions, use absolute paths:

<!-- Link to different version -->
See [v4.0 documentation](/product-docs/4.0/guide/feature)

<!-- Link within current version -->
See [feature guide](./feature)

ExternalSite Component

For linking to other documentation sites with version awareness:

<ExternalSiteLink 
  name="api-docs" 
  href="/reference/api"
  children="API Reference" 
/>

This uses the version configuration from sites.yaml.

Version Deprecation

Marking Old Versions

Add a deprecation notice to old versions:

docs/en/index.md

import { Directive } from '@alauda/doom/runtime'

<Directive type="warning" title="Deprecated Version">
  This documentation is for v3.9, which is no longer supported. 
  Please upgrade to [v4.1](/product-docs/4.1/) for the latest features and security updates.
</Directive>

Removing Old Versions

Remove from versions.yaml

Delete the version entry:

- '4.1'
- '4.0'
# Removed: - '3.9'

Delete version directory

Remove the build output:

rm -rf dist/product-docs/3.9

Add redirect (optional)

Redirect old URLs to the latest version:

# Nginx redirect
rewrite ^/product-docs/3.9/(.*)$ /product-docs/4.1/$1 permanent;

Version Maintenance Workflow

Creating a New Version

Create release branch

git checkout -b release-4.2

Update documentation

Make version-specific changes to content.

Build version

doom build -v 4.2

Update versions.yaml

Add new version to the list:

- '4.2'  # New version
- '4.1'
- '4.0'

Update root redirect

Point to the new latest version:

<meta http-equiv="refresh" content="0; url=/product-docs/4.2">

Deploy

Deploy all updated files to your hosting platform.

Backporting Changes

To update an older version:

# Checkout the version branch
git checkout release-4.0

# Make changes
vim docs/en/guide/feature.md

# Rebuild that version
doom build -v 4.0

# Deploy only that version
rsync -av dist/product-docs/4.0/ server:/var/www/docs/product-docs/4.0/

Best Practices

Version naming conventions

Use consistent version naming across product and docs
Prefer Major.Minor (4.0, 4.1) over full semantic versioning for docs
Use “master” or “latest” for development versions
Reserve “unversioned” for single-version projects

Version lifecycle

Maintain at least 2-3 recent major versions
Clearly mark deprecated versions
Add deprecation notices 3-6 months before removal
Keep security-critical versions longer

Build efficiency

Only rebuild changed versions
Use CI/CD to automate version builds
Cache dependencies between builds
Build versions in parallel when possible

User experience

Default to the latest stable version
Make version switcher prominent
Show version in page footer or header
Preserve user’s selected version in localStorage

Troubleshooting

Version switcher not appearing

Ensure versions.yaml exists at the correct location:

dist/
└── product-docs/
    ├── versions.yaml  ← Must be here
    ├── 4.0/
    └── 4.1/

Wrong version displayed

Check your version string:

# Correct
doom build -v 4.0

# Incorrect (will be treated as part of path)
doom build -v v4.0

Assets not loading across versions

Use absolute paths for shared assets:

<!-- Correct -->
![Logo](/logo.svg)

<!-- Incorrect (version-specific path) -->
![Logo](./logo.svg)

Advanced Scenarios

Multi-Product Versioning

Manage versions for multiple products:

sites.yaml

- name: platform-docs
  base: /platform
  version: v4.1
  
- name: api-docs
  base: /api
  version: v2.0
  
- name: cli-docs
  base: /cli
  version: v1.5

Each product can have independent versioning.

Preview Versions

Build preview versions for testing:

doom build -v preview-feature-xyz

Deploy to a preview environment:

https://preview.docs.example.com/product-docs/preview-feature-xyz/

Next Steps

Deployment

Learn deployment strategies for versioned docs

Build Command

Explore all build command options

Configuration

Configure version-specific settings

Sites Configuration

Multi-site version coordination

Get Started

Core Concepts

Features

Guides

​Version Management

​Understanding Versions

​Version URL Structure

​Unversioned Builds

​Building Versions

​Version Types

​Version Strategy

​Semantic Versioning

​Branch-Based Versioning

​Git-Based Automation

​Managing Multiple Versions

​Directory Structure

​Version List Configuration

​Root Redirect Page

​Automated Version Builds

​GitHub Actions

​GitLab CI

​Version-Specific Configuration

​Per-Version Overrides

​Build-Time Version Variables

​Version Switcher UI

​Customizing Version Labels

​Cross-Version Linking

​ExternalSite Component

​Version Deprecation

​Marking Old Versions

​Removing Old Versions

​Version Maintenance Workflow

​Creating a New Version

​Backporting Changes

​Best Practices

​Troubleshooting

​Advanced Scenarios

​Multi-Product Versioning

​Preview Versions

​Next Steps

Deployment

Build Command

Configuration

Sites Configuration

Build docs developers (and LLMs) love

Version Management

Understanding Versions

Version URL Structure

Unversioned Builds

Building Versions

Version Types

Version Strategy

Semantic Versioning

Branch-Based Versioning

Git-Based Automation

Managing Multiple Versions

Directory Structure

Version List Configuration

Root Redirect Page

Automated Version Builds

GitHub Actions

GitLab CI

Version-Specific Configuration

Per-Version Overrides

Build-Time Version Variables

Version Switcher UI

Customizing Version Labels

Cross-Version Linking

ExternalSite Component

Version Deprecation

Marking Old Versions

Removing Old Versions

Version Maintenance Workflow

Creating a New Version

Backporting Changes

Best Practices

Troubleshooting

Advanced Scenarios

Multi-Product Versioning

Preview Versions

Next Steps