Von TypeDoc migrieren

Ardo 6 entfernt die TypeDoc-Integration. API-Dokumentation aus Quellcode nutzt natives TypeScript für geprüfte Deklarationen und OXC zur Markdown-Extraktion. Betroffen sind typedoc, TypeDocConfig, ardo/typedoc, ardo/typedoc/components und die TypeDoc-Optionen des eingestellten Starters create-ardo.

Native Werkzeuge installieren

Installiere den unterstützten Compiler und Parser im Dokumentationsprojekt:

pnpm add -D typescript@7.1.0-dev.20261011.1 oxc-parser@^0.155.0

Der Compiler ist ein festgelegter TypeScript-7.1-Nightly-Build und prüft auch die Projekttypen. Der nativen API von TypeScript 7.0 fehlen benötigte Funktionen. Allgemeine Dokumentationswebsites benötigen diese optionalen Pakete nicht. Entferne direkte TypeDoc-Abhängigkeiten und Plugins, die nur der alten Integration dienten.

Ardo-Konfiguration aktualisieren

Entferne typedoc aus der alten Vite-Konfiguration. Ergänze api in ardo.config.ts mit einer expliziten TypeScript-Konfiguration:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  api: {
    entryPoints: ["./src/index.ts"],
    tsconfig: "./tsconfig.api.json",
    out: "api-reference",
    title: "API Reference",
  },
})

Jede Konfiguration mit typedoc, auch typedoc: false, löst jetzt einen Migrationsfehler aus. Entferne die Option, um die Generierung zu deaktivieren. api: true nutzt src/index.ts und tsconfig.json. Eine explizite Projektgrenze hilft, wenn Dokumentation und Bibliotheksquellen dasselbe Verzeichnis teilen:

{
  "extends": "./tsconfig.json",
  "files": ["src/index.ts"],
  "include": []
}

Nimm erforderliche globale Deklarationen ebenfalls in files auf. Ardo aktiviert geprüfte Deklarationsausgabe und behält Kommentare im Speicher, ohne Konfiguration oder Festplatte zu verändern. Compilerfehler stoppen den ersten Build. In Entwicklung bleiben die letzten gültigen Seiten erhalten; Fehler erscheinen im Vite-Overlay. Nach der Korrektur läuft die Generierung weiter.

Vorhandene Anpassungen zuordnen

Der Extraktor beachtet @internal und lässt private/geschützte Mitglieder bei der Erweiterung aus. Wähle dokumentierte Exporte über öffentliche Einstiegspunkte. Prüfe TypeDoc-spezifische Ausschlüsse und Gruppierungen, statt eine identische Umsetzung anzunehmen. Seitenorganisation und einige Pfade unterscheiden sich; kontrolliere Links nach der Neugenerierung.

Konfiguriere für mehrere Pakete ein Array mit getrennten Ausgabeverzeichnissen wie unter Mehrere Pakete. Setup und Paketgrenze der Dokumentationsanwendung bleiben gleich.

Programmatische Hosts und Setup aktualisieren

Ersetze generateApiDocs aus ardo/typedoc durch die einmalige native API:

import { generateNativeDocs } from "ardo/api"

await generateNativeDocs(
  { entryPoints: ["./src/index.ts"], tsconfig: "./tsconfig.api.json" },
  "./app/routes"
)

Verwende für einen eigenen Watcher NativeApiProject wieder, übergib absolute Pfade geänderter, erstellter und gelöschter Dateien an extract oder generate und schließe das Projekt beim Beenden. Die normale Vite-Integration übernimmt diesen Lebenszyklus selbst.

Ardo 6 stellt create-ardo ein. Nutze die Anleitung für Agenten und API-Dokumentation für native Werkzeuge, Quellkonfiguration und ein API-Beispiel. Migriere eine angepasste Vite-Konfiguration nach diesen Schritten, statt sie zu ersetzen.

Migration prüfen

Führe Typprüfung und Build aus, kontrolliere generierte API-Seiten und Links und teste eine Quell- oder JSDoc-Änderung in Entwicklung. Halte eigene Inhalte außerhalb des generierten Verzeichnisses. Ardo-Seiten werden vor Ort aktualisiert, veraltete entfernt; nicht markierte eigene Verzeichnisse sind geschützt.

Der native Compiler kann Code ablehnen, den JavaScript-TypeScript akzeptiert. Der Extraktor deckt nicht alle TypeDoc-Funktionen ab: Namespace-Seiten, Originalquelllinks, vollständiges TSDoc und beliebige gemappte/bedingte Mitglieder bleiben Grenzen der nativen Integration. Nicht unterstützte Erweiterungen erhalten den Typausdruck und melden Diagnosen. Prüfe diese für deine API. Bleibe bei der bisherigen Ardo-Version und Konfiguration, wenn du die Umstellung aufschieben möchtest.