Versions

When a release changes how your project works, readers of older releases still need the old docs. Clay keeps older versions of the docs online next to the current ones, each with its own navigation, search and URLs.

#How versions work

• docs/ is always the latest version. It lives at the root of the site: /guides/setup.
• Each folder in docs-archive/ is an older version, a copy of docs/ saved when that version was current. docs-archive/1.x/ lives under /1.x: /1.x/guides/setup.

my-project/
├── clay.yaml
├── docs/                 # latest, at /
└── docs-archive/
    ├── 2.x/              # at /2.x
    │   ├── index.md
    │   └── guides/
    └── 1.x/              # at /1.x

Most projects never need versions: without docs-archive/, Clay shows no version switcher at all.

#Saving a version

Right before a release changes the docs, save the current state:

npx clay version 2.x

This copies docs/ into docs-archive/2.x/. In clay edit, V does the same and switches the editor to the new version. Then update docs/ for the new release, and give it a label in clay.yaml:

version: "3.x"

Without version, the switcher calls the latest docs “Latest”.

Version names become part of URLs, so they may contain letters, digits, ., - and _. docs, api, _clay and _nuxt are reserved.

#The version switcher

As soon as there is a folder in docs-archive/, the navbar shows a version switcher, newest first. Switching keeps the page you are reading when the other version has it, and otherwise opens that version’s start page. It keeps the language too.

Pages of older versions show a banner that says which version they belong to and links to the same page in the latest version.

#What each version has of its own

clay.yaml is shared: all versions have the same title and navbar.

#Editing older versions

Older versions are plain files: fix a typo in docs-archive/1.x/ like anywhere else, or switch clay edit to the version with v. Links inside an older version stay in that version, as long as they are relative: [Setup](setup.md) links to /1.x/setup. Links starting with / lead to the latest version.