Versionen

Wenn ein Release ändert, wie dein Projekt funktioniert, brauchen Nutzer älterer Releases weiterhin die alte Dokumentation. Clay hält ältere Versionen der Dokumentation neben der aktuellen online, jede mit eigener Navigation, Suche und eigenen URLs.

#So funktionieren Versionen

• docs/ ist immer die neueste Version. Sie liegt an der Wurzel der Seite: /guides/setup.
• Jeder Ordner in docs-archive/ ist eine ältere Version, eine Kopie von docs/, gespeichert, als diese Version aktuell war. docs-archive/1.x/ liegt unter /1.x: /1.x/guides/setup.

mein-projekt/
├── clay.yaml
├── docs/                 # neueste, unter /
└── docs-archive/
    ├── 2.x/              # unter /2.x
    │   ├── index.md
    │   └── guides/
    └── 1.x/              # unter /1.x

Die meisten Projekte brauchen nie Versionen: Ohne docs-archive/ zeigt Clay gar keinen Versionsumschalter.

#Eine Version speichern

Speichere den aktuellen Stand direkt bevor ein Release die Dokumentation ändert:

npx clay version 2.x

Das kopiert docs/ nach docs-archive/2.x/. In clay edit tut V dasselbe und wechselt den Editor zur neuen Version. Danach passt du docs/ an das neue Release an und gibst ihm in der clay.yaml eine Bezeichnung:

version: "3.x"

Ohne version nennt der Umschalter die neueste Dokumentation „Latest“.

Versionsnamen werden Teil von URLs. Sie dürfen deshalb Buchstaben, Ziffern, ., - und _ enthalten. docs, api, _clay und _nuxt sind reserviert.

#Der Versionsumschalter

Sobald es einen Ordner in docs-archive/ gibt, zeigt die Navigationsleiste einen Versionsumschalter, neueste zuerst. Beim Wechseln bleibt die Seite, die du liest, wenn die andere Version sie hat; sonst öffnet sich die Startseite dieser Version. Auch die Sprache bleibt erhalten.

Seiten älterer Versionen zeigen ein Banner, das sagt, zu welcher Version sie gehören, und auf dieselbe Seite in der neuesten Version verlinkt.

#Was jede Version für sich hat

Die clay.yaml teilen sich alle Versionen: Sie haben denselben Titel und dieselbe Navigationsleiste.

#Ältere Versionen bearbeiten

Ältere Versionen sind ganz normale Dateien: Einen Tippfehler in docs-archive/1.x/ behebst du wie überall sonst, oder du wechselst clay edit mit v zur Version. Links in einer älteren Version bleiben in dieser Version, solange sie relativ sind: [Einrichtung](setup.md) verlinkt auf /1.x/setup. Links, die mit / beginnen, führen zur neuesten Version.