Advanced Versioning

Overview

Enterprise versioning extends the standard directory-based 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:

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

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