> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Versioning

Enterprise versioning features including branch-based versions, access control per version, and automatic version management.

## Overview

Enterprise versioning extends the standard [directory-based versioning](/versioning) with additional capabilities for organizations managing documentation across multiple product versions, releases, and customer tiers.

## Branch-Based Versions

Instead of maintaining version directories in a single branch, enterprise customers can map Git branches to documentation versions:

| Branch | Version | Status |
|---|---|---|
| `main` | v3.0 (latest) | Default |
| `release/v2` | v2.0 | Stable |
| `release/v1` | v1.0 | Deprecated |

Each branch is built and deployed independently, sharing the same project and domain but with version-specific content.

## Version Access Control

Combine versioning with RBAC to restrict access to specific versions:

```json
{
  "auth": {
    "enabled": true,
    "groups": {
      "beta-testers": {
        "label": "Beta Testers",
        "pages": ["v4-beta/*"]
      },
      "enterprise-customers": {
        "label": "Enterprise",
        "pages": ["v3/*", "v2/*", "v1/*"]
      }
    }
  }
}
```

This allows you to:
- Share pre-release documentation with beta testers
- Restrict legacy version access to paying customers
- Gate new features behind enterprise tiers

## Version Lifecycle Management

**Development**

New version is created in a feature branch. Preview deployments let the team review before release.
  **Beta**

Beta documentation is published with restricted access. Only users in the beta group can view it.
  **Release**

Version is promoted to stable. Access restrictions are removed and it becomes the new default.
  **Maintenance**

Previous version moves to maintenance mode. Bug fixes are applied but no new features.
  **Deprecation**

Version is marked as deprecated. A banner warns readers to migrate to the latest version.
  **End of Life**

Version is hidden from the dropdown but remains accessible by URL for existing users.

## Deprecation Banners

Add a persistent banner to deprecated versions:

```json
{
  "banner": {
    "content": "This version is deprecated. Please upgrade to <a href='/v3/introduction'>v3.0</a>.",
    "dismissible": false
  }
}
```

## Version Redirects

Configure redirects to route readers from old version paths to new ones:

```json
{
  "redirects": [
    { "source": "/v1/auth", "destination": "/v2/authentication", "permanent": true },
    { "source": "/v1/users", "destination": "/v2/api/users", "permanent": true }
  ]
}
```

Use permanent redirects (301) for deprecated pages and temporary redirects (302) for pages that might return. Search engines update their index for permanent redirects.

## Version-Specific AI Index

Each version maintains its own AI search index. When a reader is viewing v2 documentation, the AI assistant and search only return results from v2 content. This prevents confusing cross-version results.

## Version Comparison

For API documentation, the agent can automatically generate changelog entries by comparing OpenAPI specs between versions:

```bash
curl -X POST "https://api.holydocs.com/api/v1/projects/PROJECT_ID/agent/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Compare the v2 and v3 OpenAPI specs and generate a migration guide"
  }'
```

## Requirements

| Feature | Plan |
|---|---|
| Directory-based versioning | All plans |
| Branch-based versioning | Enterprise |
| Version access control | Business+ |
| Version-specific AI index | Business+ |
| Automatic deprecation banners | Pro+ |