Skip to main content

Documentation Versioning

Managing documentation versions across releases using mike

Overview​

NeuroLink documentation uses mike to maintain multiple versions of documentation for different releases. This allows users to view documentation for the specific version they're using.

Benefits​

  • Version-specific docs: Users can view docs matching their installed version
  • Preserved history: Old versions remain accessible
  • Easy switching: Version selector in navigation
  • Automated deployment: Integrate with CI/CD for automatic publishing

Setup​

1. Install Dependencies​

# Install mike (already in requirements.txt)
pip install -r requirements.txt

2. Verify Configuration​

The mkdocs.yml already includes mike configuration:

extra:
  version:
    provider: mike
    default: latest

Local Usage​

Create First Version​

# Deploy current docs as version 1.0
mike deploy 1.0 latest --update-aliases

# Set 1.0 as the default version
mike set-default latest

Deploy New Version​

# Deploy new version 1.1
mike deploy 1.1 latest --update-aliases

# Deploy specific version without making it latest
mike deploy 1.0.5

List All Versions​

mike list

Output:

1.0 [latest]
1.1
1.2

Serve Versioned Docs Locally​

mike serve

Visit http://localhost:8000 to test version switching.

Delete a Version​

mike delete 1.0

Version Management Workflow​

For Minor Releases (1.0 → 1.1)​

# 1. Update docs for new features
# 2. Deploy new version
mike deploy 1.1 latest --update-aliases --push

# 3. Verify
mike list

For Major Releases (1.x → 2.0)​

# 1. Create new version
mike deploy 2.0 latest --update-aliases --push

# 2. Keep 1.x docs accessible
mike list
# Output:
# 1.9
# 2.0 [latest]

For Patch Releases (1.0.0 → 1.0.1)​

# Update existing version (same alias)
mike deploy 1.0 latest --update-aliases --push

CI/CD Integration​

GitHub Actions Workflow​

Create .github/workflows/docs.yml:

name: Documentation

on:
  push:
    branches:
      - release
    tags:
      - "v*"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for mike

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.x"

      - name: Install dependencies
        run: |
          pip install -r docs/improve-docs/requirements.txt

      - name: Configure Git
        run: |
          git config user.name github-actions
          git config user.email [email protected]

      - name: Deploy documentation
        run: |
          VERSION=${GITHUB_REF#refs/tags/v}
          cd docs/improve-docs
          mike deploy $VERSION latest --update-aliases --push

Automatic Version Detection​

- name: Deploy documentation
  run: |
    # Get version from package.json
    VERSION=$(node -p "require('./package.json').version")
    cd docs/improve-docs

    # Deploy with version
    if [[ $VERSION == *"-"* ]]; then
      # Pre-release (1.0.0-beta.1)
      mike deploy $VERSION --push
    else
      # Stable release
      mike deploy $VERSION latest --update-aliases --push
    fi

Best Practices​

1. Version Naming​

  • Stable releases: 1.0, 1.1, 2.0 (match npm version)
  • Pre-releases: 1.0-beta, 2.0-rc1
  • Development: dev (always latest from main branch)

2. Alias Strategy​

# Latest stable release
mike deploy 1.5 latest stable --update-aliases

# Development version
mike deploy dev --update-aliases

# Long-term support
mike deploy 1.0 lts --update-aliases

3. Version Cleanup​

# Remove old versions (keep last 3 major versions)
mike delete 0.9
mike delete 1.0

4. Documentation Updates​

For bug fixes to old versions:

# Checkout old version
git checkout v1.0.0

# Make documentation fixes
# ...

# Redeploy specific version
mike deploy 1.0 --push

Advanced Configuration​

Custom Version Selector​

Add to mkdocs.yml:

extra:
  version:
    provider: mike
    default: latest
    alias: true

Version Warnings​

Add version-specific warnings in docs/index.md:

:::warning[Deprecated Version]
You're viewing documentation for version 1.0, which is no longer supported.
Please upgrade to the latest version.

:::

Troubleshooting​

Issue: "gh-pages branch not found"​

# Create gh-pages branch
git checkout --orphan gh-pages
git rm -rf .
git commit --allow-empty -m "Initialize gh-pages"
git push origin gh-pages
git checkout main

Issue: Version selector not appearing​

Verify mike is installed:

mike --version

Check mkdocs.yml configuration:

extra:
  version:
    provider: mike # Must be set

Issue: Wrong default version​

# Set correct default
mike set-default latest
mike serve  # Verify locally

Version History​

VersionRelease DateStatusNotes
7.47.xCurrent✅ ActiveLatest features
7.46.x2024-12✅ ActivePrevious stable
7.45.x2024-11⚠️ OldSecurity updates only
< 7.452024 and earlier❌ UnsupportedUpgrade recommended

Additional Resources​