Keep documentation for older releases

A historical site lets someone using version 1.0 read the version 1.0 guide, even after version 2.0 changes the project. DocSprout builds each release from the files saved in that release’s Git tag.

If you only want the latest documentation, you can skip this page and use the single-version Pages path.

Create the version manifest

Save docs/versions.json:

{
  "schema_version": 1,
  "current": "1.1.0",
  "versions": [
    {"release": "1.1.0", "source_ref": "v1.1.0"},
    {"release": "1.0.0", "source_ref": "v1.0.0"}
  ]
}

release is the label readers see. source_ref is the Git tag containing that release’s files. current must match one item in the list.

Use a tag such as v1.1.0 or a full 40-character commit SHA. Do not use a moving branch name such as main, because its files can change later.

Why the release check is strict

Run this after committing the manifest and creating the current tag:

docsprout check-release

The check confirms that:

• every source ref exists and cannot move by accident;
• each release and source ref appears only once;
• the current source ref points to HEAD, the commit you have checked out;
• documentation changes have been committed.

These rules prevent a public release label from quietly showing different words later. The glossary explains HEAD, immutable, source ref, tag and SHA.

Build every release

Run:

docsprout build-all --output build/docs-site

DocSprout reads every tag into a temporary folder and builds only the files that existed there. It never copies today’s guide into an older release.

Older tags do not need DocSprout configuration. If a tag contains only Markdown, DocSprout creates simple navigation from those historical files. It chooses a home page from index.md, README.md, a familiar start page, or the first available document.

Follow the safe release order

The order is: update manifest, check, commit the release branch, push it, open the PR, wait for CI, merge, create the annotated tag on the merge commit, run the release check and full build, then push the tag. Use the exact commands in the pre-publish checklist.

The maintained historical example demonstrates two small releases. Its automated test builds the same Git history twice and compares every generated byte.