Versions

Snapshots

Record active docs without overwriting an existing edition:

markupress snapshot v1
markupress build

The command validates a build and writes versions/v1/, a copy of the project's layout: versions/v1/docs/ and versions/v1/public/. It stages the copy in a .-prefixed folder and renames it into place, so a version appears whole. The folders in versions/ are the version list: the current version first, then each snapshot, highest number first (v10, v2, v1), labelled by its folder name. It mirrors Markdown, public assets and project-local component, controller, stylesheet and asset dependencies, preserving relative imports. Existing snapshots are never replaced. Keep those files in version control. Package imports continue to use the project's installed dependencies and lockfile; snapshots freeze authored sources rather than vendoring npm packages.

A snapshot freezes everything it copies, @/ links included. In each copied Markdown, HTML, CSS, TypeScript or JavaScript file, a @/ path in an href, src or controller, an @import or a module import that names a file the snapshot copies becomes @/versions/<id>/…, so versions/v1/ reads its own copy of app/components/counter.html while the current version reads the live one. Code examples in Markdown stay as written. A @/ path to a file outside the snapshot keeps naming the project's file, and the snapshot warns with the file's name.

Absolute filesystem imports and remote resources retain their external ownership. If a snapshot process crashes, check that it has stopped before removing its versions/.snapshot-lock directory; the next snapshot replaces any .<id>-pending folder it left.

The versions option

The versions option sets the versions, their order and their labels in place of the folder list:

{
  "versions": [
    { "id": "current", "label": "Next", "directory": "docs" },
    { "id": "v1", "label": "Version 1", "directory": "versions/v1/docs", "publicDir": "versions/v1/public" }
  ],
  "defaultVersion": "v1"
}

The version switcher

A site with several versions shows their links in the sidebar and the selected version's label beside the title. Version IDs are URL slugs; they need not follow SemVer. A document's id identifies it across versions independently of its filename, route and generated component name. The version selector links to that identity in the other version, even if its route changed. If it is absent, the selector explains the fallback and links to that version's home. Selection lives in the URL and survives reloads.

Canonical pages

The default version serves the site root with unversioned URLs. Older versions use /v/<id>/, for example /v/1.2.3/. Current links, navigation and search results use the root paths. A historical version serving the same source directory as another version is an alias of its owning pages.