Versionado y retención

La documentación se desactualiza cuando se abandonan las versiones antiguas. plasmoid trata el versionado como una función de primera clase: las publicaciones se mantienen sincronizadas con el semver de tu proyecto, y las versiones antiguas nunca se eliminan.

De dónde viene la versión

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

source = "cargo" (por defecto) lee package.version del Cargo.toml ubicado un nivel por encima de tu directorio de documentación.
source = "manual" requiere que pases --version en cada compilación (para proyectos que no son de Rust).

En cualquier caso, --version X.Y.Z en la línea de comandos prevalece si se proporciona.

Estructura de salida

Cada versión se renderiza en su propio directorio:

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

Volver a compilar la misma versión la sobrescribe en su lugar: corregir una errata en la documentación de la publicación actual no crea una nueva versión.

Retención

retain (por defecto 5) establece cuántas de las versiones más recientes permanecen activas, navegables como HTML. Las versiones más antiguas se archivan en zip en /archive/ y se listan en la página /versions/ como descargas. Nunca se descarta nada; cambias la navegación en vivo por un árbol servido más pequeño, manteniendo a la vez el registro histórico.

“Última actualización” por página

La versión de publicación y la frescura del documento son ejes distintos. Cada página también lleva una fecha de “Última actualización”, tomada del commit de git más reciente del archivo (que recae en el mtime del sistema de archivos cuando el historial de git no está disponible). Así, una página puede indicar “versión 1.2.0 · Última actualización 2026-03-04”: la publicación a la que pertenece, y cuándo cambió realmente su contenido.

plasmoid ejecuta un único git log por lotes para todo el árbol, no uno por página, así que estampar la frescura sigue siendo barato incluso en conjuntos de documentación grandes.

Cambiar de versión conserva tu lugar

El selector de versiones de la cabecera es consciente de la versión: elige otra publicación y aterrizas en la misma página de esa versión, no de vuelta en su inicio. Para que eso sea seguro, cada compilación escribe un pequeño /<version>/paths.json que lista las páginas que emitió; el selector enlaza la misma ruta solo cuando la versión de destino realmente la tiene, y de lo contrario recae en el inicio de esa versión, de modo que cambiar nunca genera enlaces rotos.

El selector (y el selector de idioma) es una divulgación nativa <details> de enlaces reales: funciona con JavaScript desactivado, es totalmente accesible con el teclado, y cada opción es un <a> real que puedes abrir con clic central o en una pestaña nueva.

Alias estables

Los lectores y los enlaces externos usan los alias estables /docs/ y /latest/, que siempre apuntan a la versión actual, así que un marcador sigue funcionando entre publicaciones.