Fehlerbehebung

Die meisten Probleme liegen an der Grenze zwischen CLI-Konfiguration, Routen in app/routes und Markdown-/MDX-Inhalten. Beginne beim passenden Symptom und vergleiche die Integration mit dem versionsgleichen Basic-Beispiel.

Installationsprobleme

Cannot find module 'ardo'

Prüfe, ob alle benötigten Abhängigkeiten installiert sind:

pnpm add ardo@6

Fehler bei der Node.js-Version

Ardo benötigt Node.js ab 22.22.0. Prüfe deine Version:

node --version

Für ein Upgrade kannst du nvm oder fnm verwenden.

Build-Probleme

Failed to resolve import

Ardos CLI ergänzt die Build-Integration automatisch. Website-Einstellungen gehören in die optionale ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Documentation",
})

Nutze vite.config.ts nur für weitere Plugins oder Vite-spezifische Einstellungen. Ardo liefert seine Integration selbst.

Grenze des Dokumentationspakets

Ardo behandelt die Vite-Projektwurzel als eigenständiges Dokumentationspaket. Halte dort eine eigene package.json und installiere deklarierte Abhängigkeiten im eigenen node_modules. Eine Installation in einem übergeordneten Verzeichnis oder der Monorepo-Wurzel ersetzt keine fehlende lokale Installation.

Ardo verwaltet React, React DOM, Vite und Standardicons; deren Importe werden aus Ardos Abhängigkeitsbaum aufgelöst. Andere direkte Importe müssen im Dokumentationspaket deklariert sein, auch wenn eine Abhängigkeit das Paket bereits nutzt. Abhängigkeiten dürfen ihre eigenen deklarierten transitiven Pakete nutzen. Normale pnpm-Verknüpfungen in den virtuellen Store werden unterstützt; dessen Speicherort ändert die Paketzugehörigkeit nicht.

Halte eigene Komponenten im Dokumentationsprojekt, etwa unter app/components/. Relative Importe, Vite-Aliasse und Symlinks zu benachbartem Workspace-Quellcode scheitern in Entwicklung und Build, ebenso Paketlinks auf solchen Komponentenquellcode. Installiere eine veröffentlichte Komponentenbibliothek. Ardos eigener Workspace-Link wird zur Framework-Entwicklung über die gebauten dist-Dateien unterstützt.

Ardo bündelt Anwendungsabhängigkeiten für SSR samt React. Komponenten und Server-Renderer verwenden dieselbe Laufzeit; eine ssr.noExternal-Liste pro Komponente ist nicht nötig. Fehlende Abhängigkeiten erzeugen einen [ardo]-Fehler statt eines Rückgriffs auf übergeordnete Installationen. Vite optimiert SSR-Abhängigkeiten in der Entwicklung automatisch, damit auch CommonJS im selben Modulgraphen läuft.

Diese Grenze betrifft den Modulgraphen der Anwendung. Explizite API- und Inhaltsquellen dürfen weiterhin zur Dokumentationsgenerierung gelesen werden; dadurch wird externer Komponentenquellcode nicht für Anwendungsimporte freigegeben.

TypeScript-Fehler in Routen

Ardo erzeugt die Routentabelle virtuell; Router-Typen müssen nicht neu gebaut werden. Prüfe die Route und ihre Importe:

1. tsconfig.json sollte ardo/tsconfig erweitern und app einschließen.
2. Importiere React-APIs und -Typen aus ardo/react.
3. Führe pnpm exec tsc --noEmit aus. Bleiben Editor-Diagnosen veraltet, starte dessen TypeScript-Server neu.
4. Behebe API- und Sammlungsfehler in Quellen und Konfiguration, nicht im generierten Markdown.

Build scheitert mit Speicherfehler

Erhöhe für große Dokumentationswebsites den Node.js-Speicher:

NODE_OPTIONS=--max-old-space-size=4096 pnpm build

Entwicklungsprobleme

Hot Reload funktioniert nicht

1. Prüfe, ob du Dateien unter app/routes/ bearbeitest.
2. Prüfe, ob der Vite-Server läuft.
3. Starte den Entwicklungsserver neu.

Stile werden nicht angewendet

Ardo lädt sein Stylesheet automatisch. Prüfe bei eigenen Stilen den CSS-Import in app/root.tsx. Stylesheet-Zuständigkeit und Kaskade erklärt das Zusammenspiel mit Ardos ardo-Layer.

Die Suche funktioniert nicht

Suchdaten entstehen in Entwicklung und Produktionsbuild aus dem Routenbaum. Vor der Entwicklungssuche ist kein separater Build nötig.

1. Prüfe, ob das Dokument unter app/routes/ oder in einer aktivierten Inhaltsquelle liegt.
2. Suche nach einem Wort aus einer Überschrift oder einem Absatz einer Markdown-/MDX-Seite.
3. Prüfe Browserkonsole und Terminal auf fehlgeschlagene Suchindex-Anfragen.
4. Starte nach Konfigurationsänderungen mit neuen Inhaltsquellen den Server neu.

Inhaltsprobleme

Markdown wird nicht gerendert

Prüfe die Datei:

1. Sie endet auf .md oder .mdx.
2. Sie liegt unter app/routes/.
3. Ihr Frontmatter ist gültig, falls vorhanden.

Codeblöcke ohne Hervorhebung

Die Hervorhebung nutzt Ferriki. Gib die Sprache an:

```javascript
const foo = "bar"
```

Unter Ferrikis Standardressourcen findest du unterstützte Sprachen und Themes. Eine unbekannte Sprache erzeugt eine Warnung und wird als einfacher Text dargestellt.

Native Engine oder Ressourcen laden nicht

Ardo benötigt Node.js 22.22 oder neuer und native Binärdateien für Linux/Windows x64/arm64 oder macOS Apple Silicon. Aktiviere optionale Abhängigkeiten bei der Installation.

Ferriki lädt Standardsprachen und Themes beim ersten Einsatz. Fülle und sichere für Offline-CI vorher einen Cache. Setze dann FERRIKI_CACHE_DIR auf dessen Pfad und FERRIKI_ASSETS_REMOTE=0, um Downloads zu deaktivieren. Fehlende Themes oder Binärdateien lassen den Build scheitern; siehe Ferriki-Fehlerbehebung.

CodeBlock ohne Hervorhebung in.tsx

ardo:codeblock-highlight benötigt ein statisches Prop language. Bei dynamischen Variablen oder Ausdrücken entfällt die Build-Hervorhebung; der Code erscheint als einfacher Text.

Code kann als Textkind, Template-Literal oder über das Prop code angegeben werden:

import { ArdoCodeBlock } from "ardo/ui"

;<ArdoCodeBlock language="typescript">const x = 42</ArdoCodeBlock>

Nutze für vollständig dynamischen Code highlightCode aus ardo/vite zur Build-Zeit:

import { highlightCode } from "ardo/vite"
const html = await highlightCode(dynamicCode, "typescript")

Bilder werden nicht geladen

Nutze relative Pfade ausgehend von der Markdown-Datei:

![Alt text](./images/screenshot.png)

Oder absolute Pfade ab dem öffentlichen Verzeichnis:

![Alt text](/images/screenshot.png)

Deployment-Probleme

404 beim Neuladen einer Seite

Ardo schreibt eine HTML-Datei pro Seite und verwendet normale Dokumentnavigation. Veröffentliche das vollständige build/client/. Der Hoster muss Verzeichnisindizes ausliefern, etwa /guide/intro/index.html für /guide/intro/. Erhalte den Basispfad und nutze Ardos 404.html für unbekannte Seiten. Deployment nennt die hosterspezifischen Einstellungen.

Gibt schon die Wurzel-URL lokal 404 zurück, ergänze app/routes/home.tsx oder app/routes/index.mdx. Prüfe vor dem erneuten Build, ob die Startseite ein vorhandenes Dokument verlinkt.

Probleme mit dem Basispfad

Setze für ein Unterverzeichnis base in ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  base: "/my-docs/",
})

Hilfe bekommen

Ist dein Problem hier nicht aufgeführt:

1. Suche in GitHub Issues nach ähnlichen Problemen.
2. Stelle Fragen in GitHub Discussions.
3. Erstelle ein Issue mit einem minimalen Reproduktionsbeispiel.