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 latest ones, each with its own navigation, search and URLs.

#How versions work

Most projects never need versions. Their pages are right in docs/, and Clay shows no version switcher.

With versions, each version has a folder of its own inside docs/:

• docs/latest/ is always the latest version. It lives at the root of the site: /guides/setup.
• Every other folder in docs/ is an older version, a copy of docs/latest/ saved when that version was current. docs/1.x/ lives under /1.x: /1.x/guides/setup.
• All versions sit at the same depth, so a path that leads out of the docs, like an include of ../../../clay.yaml, works the same in each copy.

This site works this way: its pages are in docs/latest/, the docs of Clay 4 in docs/4.x/ and those of Clay 3 in docs/3.x/, online at /4.x and /3.x.

#Saving a version

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

#The first version

While the pages are right in docs/, the first clay version moves them into docs/latest/ before it saves the copy. It shows what it is about to do and asks first:

┌  Clay 5.1.0 · version
│
│  Clay keeps each version of the docs in a folder of its own inside docs/:
│
│    docs/latest/  at /     the latest docs: docs/ moves here (110 files)
│    docs/1.x/     at /1.x  a copy of docs/latest/
│
│  Every version sits at the same depth, so paths that lead out of docs/ work in each copy.
│
│  docs/latest/ is one level deeper than docs/, so Clay changes these paths:
│    docs/latest/writing/snippets.md: ../../clay.yaml#variables → ../../../clay.yaml#variables
│
│  These name paths in docs/, which Clay does not change; point them into docs/latest/ if they mean the latest docs:
│    .gitignore: docs/api/
│
│  Git keeps the history of the moved files. Commit the move on its own, so it is easy to review.
│
◆  Go ahead? (y/N)

• Paths that lead out of docs/ get one more ../: includes, links, images and files in HTML. Paths within the docs move along and stay as they are.
• favicon and navbar.logo in clay.yaml follow when they point into docs/.
• Commands and lists that name paths in docs/, like generate in clay.yaml, .gitignore or the scripts in package.json, are listed for you to check: only you know whether they mean the latest docs.
• Dates stay: Clay reads “last updated” from git, which sees the move as a rename.

In scripts and CI, where nobody can answer, add --yes. Without it, nothing changes.

#The version switcher

As soon as there is an older version, 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/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.