Versioning
Set up documentation versioning in HolyDocs to maintain docs for multiple product versions simultaneously.
Overview
HolyDocs supports directory-based documentation versioning. This lets you maintain separate documentation sets for different versions of your product while sharing a single project and domain.
Directory-Based Versioning
Organize your docs into version directories:
textdocs/ docs.json v2/ introduction.mdx quickstart.mdx api/ users.mdx v1/ introduction.mdx quickstart.mdx api/ users.mdx
Configuring Versions
Define available versions in the navigation.versions field of your docs.json:
json{ "navigation": { "versions": [ { "name": "v2.0", "url": "/v2", "default": true }, { "name": "v1.0", "url": "/v1" } ], "groups": [ { "group": "Getting Started", "pages": ["v2/introduction", "v2/quickstart"] } ] }}
Version Properties
| Property | Type | Description |
|---|---|---|
name | string | Display name in the version selector dropdown |
url | string | URL prefix for this version |
default | boolean | Whether this is the default version (shown when no version prefix is in the URL) |
hidden | boolean | Hide from the dropdown but keep accessible by URL |
Version Selector
When versions are configured, a dropdown appears in the sidebar allowing readers to switch between versions. The selected version persists in the URL path:
docs.yourcompany.com/v2/quickstart— Version 2 quickstartdocs.yourcompany.com/v1/quickstart— Version 1 quickstart
Navigation Per Version
Each version typically has its own navigation groups. You can structure this by using separate groups per version or by dynamically generating navigation:
json{ "navigation": { "versions": [ { "name": "v2.0", "url": "/v2", "default": true }, { "name": "v1.0", "url": "/v1" } ], "tabs": [ { "tab": "Documentation", "groups": [ { "group": "Getting Started", "pages": ["v2/introduction", "v2/quickstart"] }, { "group": "API Reference", "pages": ["v2/api/users", "v2/api/projects"] } ] } ] }}
For large projects with many versions, consider using separate docs.json files per version and the HolyDocs CLI to merge them during the build process.
Shared Content Between Versions
Not all content changes between versions. For pages that are identical across versions (e.g., authentication guides, general concepts, support pages), use the shared directory pattern:
textdocs/ docs.json shared/ authentication.mdx support.mdx faq.mdx v2/ introduction.mdx quickstart.mdx v1/ introduction.mdx quickstart.mdx
Reference shared pages in the navigation for each version:
json{ "navigation": { "versions": [ { "name": "v2.0", "url": "/v2", "default": true }, { "name": "v1.0", "url": "/v1" } ], "tabs": [ { "tab": "Documentation", "groups": [ { "group": "Getting Started", "pages": ["v2/introduction", "v2/quickstart"] }, { "group": "General", "pages": ["shared/authentication", "shared/faq", "shared/support"] } ] } ] }}
Shared pages appear at the same URL regardless of the selected version. When a reader switches versions, they stay on the shared page rather than navigating to a version-specific equivalent.
Hidden Versions
Set hidden: true to keep a version accessible by URL but remove it from the dropdown. This is useful for deprecated versions:
json{ "name": "v0.9 (deprecated)", "url": "/v0.9", "hidden": true }
Best Practices
- Default to latest — Set the newest stable version as
default: true - Deprecation notices — Add a
<Callout type="warning">at the top of deprecated version pages - Shared assets — Store images and assets in a top-level
images/directory accessible from all versions - Redirect old URLs — Use the
redirectsconfig to redirect removed pages to their new locations
json{ "redirects": [ { "source": "/v0.9/quickstart", "destination": "/v1/quickstart", "permanent": true } ]}
Redirect Patterns
Use these redirect patterns for common version migration scenarios:
json{ "redirects": [ { "source": "/v0.9/:path*", "destination": "/v1/:path*", "permanent": true }, { "source": "/docs/old-page", "destination": "/v2/new-page", "permanent": true }, { "source": "/latest/:path*", "destination": "/v2/:path*", "permanent": false } ]}
| Pattern | Use Case |
|---|---|
/v0.9/:path* → /v1/:path* | Redirect an entire deprecated version to its successor |
| Specific page redirect | When a page was renamed or restructured between versions |
/latest/:path* → /v2/:path* | Provide a "latest" alias that always resolves to the current default version |
Use permanent: true (301) for version deprecations — this tells search engines to update their index. Use permanent: false (302) for aliases like /latest/ that will change when a new version is released.
Migration Between Versions
When releasing a new version, follow this workflow:
Copy the previous version directory
Duplicate the current default version directory as the new version:
bashcp -r docs/v2 docs/v3
Update docs.json
Add the new version and set it as default. Move the previous version down in the list:
json{ "navigation": { "versions": [ { "name": "v3.0", "url": "/v3", "default": true }, { "name": "v2.0", "url": "/v2" }, { "name": "v1.0", "url": "/v1", "hidden": true } ] }}
Update navigation groups
Update page references in the navigation to point to the new version directory (v3/introduction instead of v2/introduction).
Add redirects for the old default
If your previous default version was accessible without a version prefix, add redirects:
json{ "redirects": [ { "source": "/quickstart", "destination": "/v3/quickstart", "permanent": false } ]}
Add deprecation notices
Add a callout at the top of pages in the old version:
mdx<Callout type="warning">You are viewing documentation for v2.0, which is no longer the latest version.See the [v3.0 documentation](/v3/introduction) for the most up-to-date content.</Callout>
Deploy and verify
Push the changes and verify that the version selector, redirects, and deprecation notices all work correctly on the live site.
Per-Version Search
When versioning is enabled, the search index is aware of version boundaries:
- Search results are scoped to the reader's currently selected version by default
- A "Search all versions" toggle in the search modal lets readers search across all versions
- The AI assistant is aware of version context and will cite pages from the selected version first
Advanced Versioning
For enterprise users who need more sophisticated versioning (branch-based versions, automatic version generation, or per-version access control), see Enterprise Versioning.