> ## 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. # 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: ``` docs/ 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 quickstart - `docs.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: ``` docs/ 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 `` 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 `redirects` config 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: ```bash cp -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 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. ``` **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](/versioning-enterprise).