Upgrade auf Ardo 4.0

Ardo 4.0 nutzt die neue Hauptversion, um die Identität von Dokumentations-URLs zu stabilisieren. Die wichtigste öffentliche Änderung ist das URL-Schema: Veröffentlichte Dokumentation sollte unter einem stabilen Hauptversionsordner wie /v3/ oder /v4/ liegen; / leitet zur aktuellen Hauptversion weiter.

Änderungen

• URLs mit Hauptversion sind die empfohlene öffentliche Form für veröffentlichte Dokumentation.
• index.html an der Wurzel, versions.json, sitemap.xml, robots.txt, llms.txt, Suchdaten und Weiterleitungsdateien sind statische Build-Ausgaben.
• sitemap.xml nennt nur die aktuelle kanonische Hauptversion. Ältere Ordner bleiben erreichbar, ohne als doppelte aktuelle Inhalte indexiert zu werden.
• GitHub-Pages-Deployments sollten ältere Hauptversionsordner erhalten, wenn eine neue Version aktuell wird.

Versionierte Dokumentation aktualisieren

Konfiguriere die aktuelle Hauptversion in vite.config.ts:

import { defineConfig } from "vite"
import { ardo } from "ardo/vite"

export default defineConfig({
  plugins: [
    ardo({
      title: "My Docs",
      siteUrl: "https://docs.example.com",
      versioning: {
        current: "v4",
        versions: [
          { id: "v4", label: "4.x", path: "/v4/" },
          { id: "v3", label: "3.x", path: "/v3/" },
        ],
      },
    }),
  ],
})

Setze denselben Basispfad in react-router.config.ts:

import type { Config } from "@react-router/dev/config"
import { withArdoVersioning } from "ardo/vite"

const config = {
  ssr: false,
  prerender: true,
} satisfies Config

export default withArdoVersioning(config, { basename: "/v4/" })

Ältere GitHub-Pages-Versionen erhalten

GitHub Pages ersetzt bei jedem Deployment das gesamte hochgeladene Artefakt. Sichere vor dem Wechsel in einen neuen Hauptversionsordner den letzten erzeugten Ordner der vorherigen Hauptversion und kopiere ihn beim Deployment in das Pages-Artefakt.

Erhältst du jeden älteren Ordner, etwa als Archiv im Repository, bleiben stabile URLs wie /v3/... beim ersten /v4/-Deployment erhalten.

Bestehende Links prüfen

Aktualisiere externe Dokumentationslinks auf die versionierte kanonische URL:

https://docs.example.com/v4/guide/getting-started

Verwende latest nicht als kanonische Adresse. Ein später ergänzter latest-Alias sollte zum aktuellen Hauptversionsordner weiterleiten.