Documentation Versions

This directory is used by mike for managing multiple documentation versions.

How Versioning Works

MAID uses mike to maintain multiple versions of documentation:

• latest - Always points to the most recent stable release
• dev - Development version (main branch)
• v0.x - Specific version documentation

Building Versioned Documentation

Deploy a New Version

# Deploy documentation for a specific version
mike deploy --push --update-aliases 0.2.0 latest

# Deploy development documentation
mike deploy --push dev

List Available Versions

mike list

Delete a Version

mike delete 0.1.0

Set Default Version

mike set-default latest

Local Development

When developing documentation locally:

# Serve current documentation (no versioning)
mkdocs serve

# Serve with versioned documentation
mike serve

Version Aliases

Alias	Description
latest	Most recent stable release
dev	Development version (unstable)
stable	Same as latest

CI/CD Integration

Documentation is automatically deployed via GitHub Actions:

1. On tag creation (v*..): Deploys versioned docs with latest alias
2. On main branch push: Deploys dev version
3. On PR: Builds docs for validation (no deployment)

See .github/workflows/docs.yml for implementation details.

File Structure

After mike deployment, the structure will be:

site/
├── 0.1.0/           # v0.1.0 documentation
├── 0.2.0/           # v0.2.0 documentation
├── dev/             # Development documentation
├── latest -> 0.2.0  # Symlink to latest stable
└── versions.json    # Version metadata

Configuration

Mike configuration is in mkdocs.yml:

plugins:
  - mike:
      alias_type: symlink
      canonical_version: latest
      version_selector: true
      css_dir: css
      javascript_dir: js

extra:
  version:
    provider: mike
    default: latest

Notes

• Always update the changelog before releasing a new version
• Migration guides should be created for major/minor versions with breaking changes
• Pre-release versions (alpha, beta, rc) should not use the latest alias