docouture new --mode offers two shapes, both real and releasable — decided once, at
scaffold time (docouture upgrade never changes it).
Standalone (Stable + Prerelease) — the default
main always builds as the prerelease version (docs/src/antora.yml:
version: prerelease, prerelease: true, permanently). A release force-moves a
single rolling docs/stable tag to a fresh commit — no historical archive, appropriate
when only "now" and "what’s next" matter.
content:
sources:
- url: ..
start_path: docs/src
branches: [main]
tags: ['docs/stable']Versioned (Full History)
main still builds as the prerelease version — docs/src/antora.yml is
byte-identical to the standalone shape on main — but every release is instead its
own immutable docs/vX.Y.Z git tag, kept forever. Appropriate for a library/SDK whose
consumers pin an old version.
content:
sources:
- url: ..
start_path: docs/src
branches: [main]
tags: ['docs/v*']A versioned-mode site additionally gets docs/.release-version — a plain-text file
holding the next release’s target version, read by docouture-release.yml instead
of a workflow input.
On a release tag, docs/src/antora.yml changes
Standalone’s docs/stable tag says version: stable, prerelease: false. A versioned
release tag says version: '1.2.0' (or whatever was released), prerelease: false.
Neither mode ever rewrites `main’s own copy.
Which one to pick
Standalone if there’s one thing to document and only "current" matters. Versioned if past releases need to keep resolving unchanged after a new one ships — an SDK, a CLI, anything consumers pin a version of. See Releasing a documentation for how a release is actually cut in either mode.
Tag names are prefixed with docs/
Release tags live under docs/ — docs/stable and docs/vX.Y.Z, not bare stable/
vX.Y.Z — so they don’t collide with a host monorepo’s own release tags. docouture
upgrade refreshes the workflow files but never touches antora-playbook.yml, so a site
scaffolded before this convention keeps its old tags: ['stable'] / tags: ['v*']
matcher until someone edits it by hand. After upgrading, update that matcher to
tags: ['docs/stable'] / tags: ['docs/v*'] — and, if a release was already cut under
the old bare name, re-push it under the new one (git tag docs/stable <sha> && git push
origin refs/tags/docs/stable, or the docs/vX.Y.Z equivalent per existing tag) — or the
next release’s tag won’t match anything the playbook aggregates.