shipyard unterstützt versionierte Dokumentation, mit der Sie mehrere Versionen Ihrer Dokumentation parallel zu Ihren Software-Releases pflegen können. Dies ist nützlich, wenn Sie Dokumentation für verschiedene Versionen Ihres Produkts oder Ihrer API bereitstellen müssen.
Mit versionierten Docs können Benutzer:
/latest/-Alias verwenden, der immer auf die aktuelle Version zeigtAktualisieren Sie Ihre astro.config.mjs, um die Versionskonfiguration hinzuzufügen:
import shipyardDocs from '@levino/shipyard-docs'
export default defineConfig({
integrations: [
shipyardDocs({
versions: {
current: 'v2',
available: [
{ version: 'v2', label: 'Version 2.0 (Aktuell)' },
{ version: 'v1', label: 'Version 1.0', banner: 'unmaintained' },
],
deprecated: ['v1'],
stable: 'v2',
},
}),
],
})Aktualisieren Sie Ihre src/content.config.ts, um den Helper für versionierte Collections zu verwenden:
import { defineCollection } from 'astro:content'
import { createVersionedDocsCollection } from '@levino/shipyard-docs'
const docs = defineCollection(
createVersionedDocsCollection('./docs', {
versions: ['v1', 'v2'],
fallbackVersion: 'v2',
}),
)
export const collections = { docs }Strukturieren Sie Ihr docs-Verzeichnis mit Versions-Unterverzeichnissen:
docs/
├── v2/
│ ├── index.md
│ ├── installation.md
│ └── configuration.md
└── v1/
├── index.md
└── installation.mdDas war’s! Ihre versionierte Dokumentation ist jetzt unter /docs/v2/, /docs/v1/ und /docs/latest/ verfügbar.
Die versions-Option in shipyardDocs() akzeptiert folgende Eigenschaften:
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
current | string | Ja | Die Standardversion, die angezeigt wird, wenn Benutzer /docs/ besuchen |
available | SingleVersionConfig[] | Ja | Array aller verfügbaren Versionen |
deprecated | string[] | Nein | Versions-Identifier, die als deprecated markiert werden sollen |
stable | string | Nein | Die stabile Release-Version (Standard: current) |
Jeder Eintrag im available-Array kann folgende Eigenschaften haben:
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
version | string | Ja | Der Versions-Identifier (z.B. "v2", "1.0.0") |
label | string | Nein | Benutzerfreundliches Label für die UI (Standard: version) |
path | string | Nein | URL-Pfad-Segment (Standard: version) |
banner | 'unreleased' | 'unmaintained' | Nein | Banner, das für diese Version angezeigt wird |
shipyardDocs({
versions: {
// Die Standardversion für /docs/
current: 'v2',
// Alle verfügbaren Versionen (Reihenfolge wichtig für UI-Anzeige)
available: [
{
version: 'v3-beta',
label: 'Version 3.0 (Beta)',
banner: 'unreleased',
},
{
version: 'v2',
label: 'Version 2.0 (Aktuell)',
},
{
version: 'v1',
label: 'Version 1.x',
banner: 'unmaintained',
},
],
// Versionen, die Deprecation-Warnungen anzeigen
deprecated: ['v1'],
// Das stabile Release
stable: 'v2',
},
})Für versionierte Docs ohne i18n:
docs/
├── v2/ # Aktuelle/neueste Version
│ ├── index.md
│ ├── getting-started.md
│ └── advanced/
│ └── configuration.md
└── v1/ # Vorherige Version
├── index.md
└── getting-started.mdWenn Sie Versionen mit i18n kombinieren, fügen Sie Locale-Verzeichnisse innerhalb jeder Version hinzu:
docs/
├── v2/
│ ├── en/
│ │ ├── index.md
│ │ └── getting-started.md
│ └── de/
│ ├── index.md
│ └── getting-started.md
└── v1/
├── en/
│ └── index.md
└── de/
└── index.mdURLs werden zu: /en/docs/v2/getting-started, /de/docs/v1/, etc.
Wichtig: Vermeiden Sie Punkte in Versionsordnernamen. Astros Content-Collection-Loader entfernt Punkte aus Ordnernamen in Dokument-IDs, was zu Problemen führen kann.
| Ordnername | Status | Hinweise |
|---|---|---|
v1/ | Gut | Einfach, sauber |
v2/ | Gut | |
next/ | Gut | Für unveröffentlichte Versionen |
v1.0/ | Vermeiden | Punkte werden aus IDs entfernt |
2.0.0/ | Vermeiden | Punkte verursachen Probleme |
Verwenden Sie die label-Eigenschaft, um die vollständige Versionsnummer in der UI anzuzeigen:
{ version: 'v2', label: 'Version 2.0.0' }| Muster | Beispiel | Beschreibung |
|---|---|---|
/docs/[version]/[...slug] | /docs/v2/installation | Standard-versionierte Route |
/docs/latest/[...slug] | /docs/latest/installation | Alias für aktuelle Version |
/docs/ | /docs/ | Weiterleitung zur aktuellen Version |
Mit aktiviertem i18n:
| Muster | Beispiel |
|---|---|
/[locale]/docs/[version]/[...slug] | /en/docs/v2/installation |
/[locale]/docs/latest/[...slug] | /de/docs/latest/installation |
/latest/-AliasDer /latest/-Alias wird automatisch für alle Seiten der aktuellen Version generiert. Dies ermöglicht es Benutzern, auf Dokumentation zu verlinken, die immer auf die neueste Version zeigt.
<!-- Verlinkt immer auf aktuelle Version -->
Siehe die [Installationsanleitung](/docs/latest/installation)Beim Release einer neuen Version:
Versionsverzeichnis erstellen
mkdir -p docs/v3Inhalte von der vorherigen Version kopieren
cp -r docs/v2/* docs/v3/Konfiguration aktualisieren
versions: {
current: 'v3', // current aktualisieren
available: [
{ version: 'v3', label: 'Version 3.0 (Aktuell)' }, // Neu hinzufügen
{ version: 'v2', label: 'Version 2.0' }, // Label aktualisieren
{ version: 'v1', label: 'Version 1.0', banner: 'unmaintained' },
],
deprecated: ['v1'], // Beibehalten oder aktualisieren
stable: 'v3', // stable aktualisieren
}Content Collection Konfiguration aktualisieren
createVersionedDocsCollection('./docs', {
versions: ['v1', 'v2', 'v3'], // Neue Version hinzufügen
fallbackVersion: 'v3', // Fallback aktualisieren
})Inhalte der neuen Version aktualisieren
Beim Deprecaten einer älteren Version:
Zur deprecated-Liste hinzufügen
deprecated: ['v1', 'v2'], // Deprecated Version hinzufügenUnmaintained-Banner hinzufügen
available: [
{ version: 'v3', label: 'Version 3.0 (Aktuell)' },
{ version: 'v2', label: 'Version 2.0', banner: 'unmaintained' }, // Banner hinzufügen
{ version: 'v1', label: 'Version 1.0', banner: 'unmaintained' },
],Sehr alte Versionen entfernen (optional)
Sie können Versionen vollständig entfernen durch:
available-Arraydeprecated-ArrayDie Version-Selector-UI erscheint automatisch in der Navbar und der mobilen Sidebar, wenn mehrere Versionen konfiguriert sind.
Der Version Selector zeigt Badges an, um Benutzern den Versionsstatus zu verdeutlichen:
| Badge | Bedeutung | Auslöser |
|---|---|---|
| stable (grün) | Stabiles Release | Entspricht der stable-Konfigurationseigenschaft |
| deprecated (gelb) | Veraltet/nicht mehr gepflegt | Im deprecated-Array oder hat banner: 'unmaintained' |
| unreleased (blau) | Vorschau/Beta-Version | Hat banner: 'unreleased' |
Mit einer Version beginnen: Bringen Sie Ihre Docs zuerst ohne Versionierung zum Laufen, dann fügen Sie Versionen hinzu, wenn Sie sie benötigen.
Versionen fokussiert halten: Pflegen Sie nur aktiv unterstützte Versionen. Entfernen Sie sehr alte Versionen, wenn sie nicht mehr relevant sind.
Breaking Changes dokumentieren: Wenn sich eine Seite zwischen Versionen erheblich ändert, dokumentieren Sie die Unterschiede klar.
Konsistente Struktur verwenden: Behalten Sie nach Möglichkeit die gleiche Seitenhierarchie über Versionen hinweg bei, damit Links beim Versionswechsel nicht brechen.
Beschreibende Labels verwenden: Machen Sie deutlich, welche Version latest/stable ist:
{ version: 'v2', label: 'Version 2.0 (Aktuell)' }Pre-Release-Versionen markieren: Verwenden Sie das unreleased-Banner für Beta/Preview-Versionen:
{ version: 'v3-beta', banner: 'unreleased' }Versionen geordnet halten: Listen Sie Versionen von neu nach alt im available-Array auf.
Jede Version generiert einen vollständigen Satz statischer Seiten. Die Gesamtzahl der Seiten wächst multiplikativ:
Gesamtseiten = (Seiten × Versionen × Sprachen) + (Seiten × Sprachen für latest-Alias)
Zum Beispiel: 100 Seiten × 5 Versionen × 3 Sprachen = 1.500+ statische HTML-Dateien.
Optimierungstipps:
Gepflegte Versionen begrenzen: Behalten Sie nur Versionen, die aktiv unterstützt werden. Entfernen Sie Versionen nach einem angemessenen Deprecation-Zeitraum.
Versionsarchivierung erwägen: Für sehr alte Versionen:
Seitenstruktur: Große einzelne Seiten sind effizienter als viele kleine. Erwägen Sie, verwandte Inhalte zu kombinieren.
Build-Performance: shipyard verwendet optimierte interne Datenstrukturen (Maps und Sets) für O(1)-Versions-Lookups während des Builds. Die Pfadgenerierung ist effizient, auch mit vielen Versionen.
Inkrementelle Einführung: Beginnen Sie mit Versionierung erst, wenn Sie sie benötigen. Eine Single-Version-Site hat keinen Overhead durch das Versionierungssystem.