Versioning

Customization•4 min read||

DocsLit supports multi-version documentation using git branches. Each version maps to a branch, and readers can switch between versions using a dropdown in the site header.

How it works

DocsLit's versioning is branch-based. Each version of your documentation lives on a separate git branch. When you build the site, DocsLit checks out each branch and builds the pages for that version.

graph LR A[main branch] -->|"Latest (0.2)"| B[Build v0.2] C[v0.1 branch] -->|"Previous"| D[Build v0.1] B --> E[dist/] D --> E

Configuration

Add a versions object to your docslit.json:

{ "name": "My Product", "versions": { "default": "0.2", "list": [ { "version": "0.2", "branch": "main", "tag": "Latest" }, { "version": "0.1", "branch": "v0.1", "tag": "Previous" } ] }, "sidebar": [...] } The version shown by default when a reader visits your site. An array of version objects, each specifying a version number, git branch, and display tag. The version identifier (e.g., 0.2, 1.0, 2.0). The git branch containing the docs for this version. A display label shown in the version dropdown (e.g., Latest, Beta, LTS).

Recommended workflow

Write and update documentation on the main branch. This always represents the latest version.

When you release a new version of your product, create a branch from main:

git checkout -b v0.2 git push origin v0.2

On main, update docslit.json to add the new frozen version and point main to the next version:

{ "versions": { "default": "0.3", "list": [ { "version": "0.3", "branch": "main", "tag": "Latest" }, { "version": "0.2", "branch": "v0.2", "tag": "Previous" }, { "version": "0.1", "branch": "v0.1" } ] } } Run docslit build. DocsLit checks out each branch and builds only the pages that changed between versions. Patch releases (0.1.5 to 0.1.6) rarely change documentation. Cut version branches on minor or major releases to avoid unnecessary maintenance overhead.

Build output

Versioned builds produce a directory structure with each version in its own folder:

The root index.html redirects to the default version. Only pages that differ between versions are rebuilt — unchanged pages are shared to keep build times fast.

Version-specific content

Use wc-versions to show different content depending on the selected version. See data display for details.