Versions Guide - Docuriser

A project's documentation publishes per version, and versions come from your repository's git tags. Every tagged version publishes unless you exclude it: Docuriser builds it (snapshotting API reference pages, topics, README, and license from the tag), and the site publishes each built bundle under its version number, with a switcher between them. This guide covers the lifecycle: tag, build, publish.

Where versions come from

Docuriser reads the plain X.Y.Z tags of the project's repository (the build.source_path checkout). Tags group by their major.minor, and each minor is one version: the site shows 2.1, built from the minor's latest patch tag (2.1.3 today, 2.1.4 tomorrow). Superseded patches never appear anywhere, and site URLs stay stable because every patch of 2.1 builds into the same versions/2.1/ directory.

The project configurator's Versions panel lists every version the tags and the built output know about:

Each row shows the Include checkbox, the Supported checkbox (see Support status below), the version's tag (the minor bright, the patch suffix dimmed: it is superseded detail), the release date (the tag's date), and a status:

• Excluded: you unchecked it, and the decision is recorded (in versions_excluded) so the tag never publishes. Excluded rows render dimmed.
• Pending: included, but the published output is missing or a newer patch tag has landed since it was built. A newly tagged version starts here, since tagging a release is already the decision to publish it. Pending versions are what the Build panel builds.
• Complete: the built output matches the minor's latest patch tag.
• Preview: a working-tree build of a minor that has no tag yet (see Previews below). It publishes as Unreleased.

Only local tags count: fetch before you refresh if the release was tagged elsewhere. Anything that isn't a plain X.Y.Z tag is ignored (the advanced log counts them).

Including and excluding

Every tagged version starts included, so a new release needs nothing here: tag it and build. Builds never edit the config; the built output is the record of what publishes. The license text comes from the source tree at build time (the manifest's build.license; see the projects guide), and the license page names it with the value of the project's License fact (say MIT), if it has one.

Unchecking a row excludes the version. If it was built, Docuriser confirms first and deletes its versions/<label>/ output; re-checking Include and building brings it back.

When you add a project whose repository already has older tags, uncheck the ones you don't want published before you build; otherwise every tagged minor builds.

Support status

Every published version has a support status:

• Latest: the newest published version. It's always supported, so its Supported box is always checked.
• Supported: an older version whose Supported box you checked (recorded in versions_supported).
• Archived: every other published version.

With nothing checked, every version but the latest is archived, which suits an app that only supports its newest release. A framework that maintains more than one line checks a version when it announces support for that line, and unchecks it at the line's end of life. Both are one-time decisions, not per-release edits.

An archived version stays published, so its docs and downloads remain available (rolling back is the usual reason to want an old app binary). Each of its doc pages opens with a banner, "Docuriser 2.0 is archived. The latest version is 3.0.", that links to the same page in the latest version, and the docs version switcher lists it as "2.0 (archived)". To take a version off the site entirely, exclude it instead.

Building

The Build panel has one button, and it tells you what it will do:

Build N Pending builds every pending version in one run, newest first. For each one, Docuriser snapshots the minor's latest patch tag into a temporary git worktree, builds the documentation bundle from that snapshot, and records which tag it built and that tag's date (a .docuriser-built file in the output). The log streams live (check Advanced Logging for the verbose lines), and the button counts back down to Nothing Pending as rows flip Complete.

One requirement to know: a tag can only build if its snapshot carries the project's in-repo .docuriser manifest (the file that lists the README, license, topics, and include directories; see the configuration reference). Tags from before the manifest existed can't build: excluded is usually their permanent home, and the first manifest-carrying patch tag is what makes a minor buildable.

The bundle lands in versions/<label>/ beside the project config:

• the API reference, parsed by libclang from the manifest's include directories (for projects that declare build.includes): a page per class and struct, a page per header, and the api.json index the sidebar's Classes, Structs, and Headers lists come from;
• a page per topic, with their carried images and a topics.json index;
• the README snapshot;
• the license snapshot (LICENSE.md, copied from the manifest's build.license) and its license page, so every version keeps the license it shipped under.

The same build scripts as docuriser-cli build <project-config>; see the CLI guide.

The patch flow

Documentation fixes to a released minor ship as a patch tag. The README and Topics editors edit your working tree, which only future tags see, so the flow is: edit, commit, tag 2.1.4, and the 2.1 row flips to Pending (the built docs are now stale relative to the tags). Build, and the same versions/2.1/ directory is rebuilt from the new tag. The release date follows the built tag, so the site always shows the date of what is actually published.

Previews

For docs that aren't tagged yet, docuriser-cli build <config> <label> --working-tree builds from the checkout as it sits and marks the output as a preview. A preview publishes like any other built version, with the release date Unreleased, which is how a project that hasn't released yet can still have docs on the site. Its row reads Preview while the minor has no tag, and Pending once it does, until a tag build replaces the preview.

What the site does with it

At site build, every built version that isn't excluded publishes under /<project>/docs/<label>/, tag builds and previews alike, and the project page gains its Documentation tab once at least one version is built. Nothing in the project config lists versions, so a site build only needs the versions/ directories: a CI job can build every version from its tags and publish without committing anything back. The newest published version fronts the project automatically: its README on the landing page, the docs tab's default, and the stable_release preset fact (see the projects guide). Its tag also caps the downloads: the sidebar serves the newest release, at or below that tag, that has a file for every {version} download row (see the configuration reference). Building a new version is what fronts it; nothing is authored. The docs sidebar's switcher covers all published versions, and the .docuriser-built provenance never publishes; it stays beside the source output.

The versions page

A project with two or more published versions gets a Versions tab after Documentation, which opens /<project>/versions.html. It lists every published version, newest first, each with:

• its label, full tag, release date, and support status;
• Docs, a link to its docs index (docs/#2.0 picks that version in the switcher);
• Source, a link to the project's source at its tag, when the project has a repo and the version was built from a tag;
• its downloads: for each download row with {version} in its url, the newest file within that version's minor, at or below its built tag. A version's rows can differ in patch (Linux 3.0.2 beside Windows 3.0.1), and a row with no file for that minor is left out. Rows with a fixed url don't appear here.

The Source link points at the tag's source tree: <repo url>/tree/<tag> for a github.com repo, and <repo url>/src/tag/<tag> for any other (the Forgejo and Gitea form, Codeberg included).

The page's downloads come from the site's downloads/ folder, the same as the sidebar's, so an old release's binaries stay downloadable for as long as its version is published. Excluding a version removes its downloads from the site at the next build. See the configuration reference for how download rows and the downloads/ folder work.

The build also emits docs/latest, a relative symlink beside the version directories pointing at the derived latest one, so /<project>/docs/latest/<page> is a stable, unversioned URL for every doc page (same directory depth, so the pages' relative links resolve unchanged). A host can then 301 bare /<project>/docs/<page> links onto it and evergreen docs links never need a version bump: each release retargets the symlink at the next deploy. Deploy with a symlink-preserving copy (rsync -a or tar both qualify; plain scp -r dereferences).