Versioning & retention

Documentation drifts out of date when old versions are abandoned. plasmoid treats versioning as a first-class feature: releases are kept in lockstep with your project’s semver, and old versions are never deleted.

Where the version comes from

[versions]
source = "cargo"   # read package.version from the project's Cargo.toml
retain = 5

• source = "cargo" (default) reads package.version from the Cargo.toml one level above your docs directory.
• source = "manual" requires you to pass --version on every build (for non-Rust projects).

Either way, --version X.Y.Z on the command line wins if provided.

Output layout

Each version renders into its own directory:

public/
  1.2.0/  en/ es/
  1.1.0/  en/
  1.0.0/  en/
  versions/        # the index of all versions, live and archived
  archive/         # zipped older versions

Re-building the same version overwrites it in place — fixing a typo in the current release’s docs doesn’t create a new version.

Retention

retain (default 5) sets how many of the newest versions stay live — browsable as HTML. Older versions are zip-archived into /archive/ and listed on the /versions/ page as downloads. Nothing is ever discarded; you trade live browsing for a smaller served tree while keeping the historical record.

“Last updated” per page

Release version and document freshness are different axes. Each page also carries a “Last updated” date, taken from the file’s most recent git commit (falling back to filesystem mtime when git history isn’t available). So a page can read “version 1.2.0 · Last updated 2026-03-04” — the release it belongs to, and when its content actually changed.

plasmoid runs a single batched git log for the whole tree, not one per page, so stamping freshness stays cheap even on large docs sets.

Switching versions keeps your place

The version switcher in the header is version-aware: pick another release and you land on the same page in that version, not back at its home. To make that safe, every build writes a small /<version>/paths.json listing the pages it emitted; the switcher links the same path only when the target version actually has it, and otherwise falls back to that version’s home — so switching never dead-links.

The switcher (and the language switcher) is a native <details> disclosure of real links: it works with JavaScript disabled, is fully keyboard-accessible, and each option is a real <a> you can middle-click or open in a new tab.

Stable aliases

Readers and external links use the stable aliases /docs/ and /latest/, which always point at the current version — so a bookmark keeps working across releases.