Fehler: docs.json nicht gefunden

Überprüfen Sie, ob der genaue Pfad in Ihrem Repository mit Ihrer Eingabe übereinstimmt Stellen Sie sicher, dass docs.json an diesem Ort vorhanden ist Prüfen Sie auf Tippfehler – bei Pfaden wird zwischen Groß- und Kleinschreibung unterschieden Denken Sie daran: Verwenden Sie docs und nicht docs/docs.json Schnellprüfung: In Ihrem Repository sollte die Datei unter [your-docs-path]/docs.json vorhanden sein

Assets werden nicht geladen

Asset-Pfade müssen relativ zu Ihrem Docs-Verzeichnis sein. Korrekt – relativ zum Docs-Verzeichnis: Falsch – absolut vom Stammverzeichnis des Repositorys: Stellen Sie sicher, dass Ihre Bilder tatsächlich unter [docs-path]/images/ vorhanden sind.

Änderungen lösen keine Builds aus

Nur Änderungen innerhalb Ihres konfigurierten Docs-Pfads lösen automatische Builds aus. Überprüfen Sie, ob Sie Dateien innerhalb des Docs-Pfads ändern Prüfen Sie, ob Sie in den richtigen Branch pushen Sehen Sie den Status der Webhook-Zustellung in den GitHub-Repository-Einstellungen ein Wenn Builds durch Änderungen außerhalb des Docs-Pfads ausgelöst werden müssen, verwenden Sie manuelle Builds oder CI-Webhooks.

Monorepo-Unterstützung

Wenn sich Ihre docs.json in einem Unterverzeichnis befindet – docs/, packages/docs/ oder an einem anderen Ort –, aktivieren Sie den Monorepo-Modus in den Projekteinstellungen und geben Sie den Pfad an. Jamdesk beschränkt Builds auf dieses Verzeichnis und ignoriert alles außerhalb davon.

Die Screenshots zeigen die Benutzeroberfläche auf Englisch.

Voraussetzungen: Sie benötigen ein mit einem GitHub-Repository verbundenes Jamdesk-Projekt, bevor Sie die Monorepo-Unterstützung konfigurieren.

So beschränkt Jamdesk Ihren Build

Schnelle Einrichtung

Projekteinstellungen öffnen

Öffnen Sie Ihr Projekt im Jamdesk-Dashboard und gehen Sie zu Settings.

Monorepo-Modus aktivieren

Aktivieren Sie im Abschnitt Git Repository die Option Set up as monorepo.

Monorepo-Umschalter in den Projekteinstellungen

Docs-Pfad eingeben

Geben Sie den Pfad zu dem Verzeichnis an, das Ihre docs.json-Datei enthält.

Eingabefeld für den Docs-Pfad mit Vorschau

Die Vorschau zeigt, wo Jamdesk nach Ihrer Konfigurationsdatei sucht.

Speichern und neu erstellen

Klicken Sie auf Save Changes, um die Änderungen anzuwenden. Ihr nächster Build verwendet den neuen Pfad.

Den Docs-Pfad verstehen

Der Docs-Pfad gibt an, wo Jamdesk Ihre docs.json-Konfigurationsdatei innerhalb des Repositorys findet.

Geben Sie nur den Verzeichnispfad ein, nicht den Dateinamen. Verwenden Sie docs und nicht docs/docs.json.

Pfadbeispiele

Repository-Struktur	Wert des Docs-Pfads
`my-repo/docs/docs.json`	`docs`
`my-repo/packages/docs/docs.json`	`packages/docs`
`my-repo/apps/website/docs/docs.json`	`apps/website/docs`
`my-repo/documentation/docs.json`	`documentation`

Was eingeschlossen wird

Wenn Sie einen Docs-Pfad festlegen, verarbeitet Jamdesk nur Dateien innerhalb dieses Verzeichnisses:

Inhaltsdateien (.mdx, .md) werden in Seiten kompiliert
Assets in Unterverzeichnissen (z. B. images/) werden eingeschlossen
Konfiguration (docs.json) definiert Ihre Website

Dateien außerhalb des Docs-Pfads werden bei Builds ignoriert.

Gängige Monorepo-Muster

Wählen Sie das Muster, das Ihrer Projektstruktur entspricht:

Dokumentation in einem Verzeichnis der obersten Ebene.

monorepo/
├── packages/
├── apps/
└── docs/                    # Docs path: docs
    ├── docs.json
    ├── introduction.mdx
    └── guides/

Docs-Pfad: docs

Mit Assets arbeiten

Asset-Pfade in docs.json sind immer relativ zu Ihrem Docs-Verzeichnis, nicht zum Stammverzeichnis des Repositorys.

Beispiel

Wenn sich Ihre Dokumentation in packages/docs/ befindet:

packages/docs/docs.json

{
  "logo": {
    "light": "/images/logo.svg"
  },
  "favicon": "/images/favicon.svg"
}

Diese Pfade verweisen auf:

packages/docs/images/logo.svg
packages/docs/images/favicon.svg

Verwenden Sie keine absoluten Pfade vom Stammverzeichnis des Repositorys. Dies funktioniert nicht:

"favicon": "/packages/docs/images/favicon.svg"

In MDX-Dateien

Für Bilder in Ihren Inhalten gilt dieselbe Regel:

![Screenshot](/images/tabs-preview.png)

Dies verweist auf ein Bild unter [docs-path]/images/tabs-preview.png.

Interne Links

Interne Links funktionieren unabhängig von Ihrer Repository-Struktur gleich. Verwenden Sie Pfade relativ zum Stammverzeichnis Ihrer Dokumentation:

[See the quickstart guide](/quickstart)
[Installation steps](/quickstart#installation)

Diese Pfade entsprechen Ihrer Navigationsstruktur, nicht Ihrem Dateisystem.

Build-Verhalten

Jamdesk überwacht nur Änderungen innerhalb des konfigurierten Docs-Pfads:

Änderungen an packages/docs/** lösen einen Build aus
Änderungen an packages/core/** lösen keinen Build aus

Dadurch bleiben Builds schnell und auf Änderungen an der Dokumentation fokussiert.

Müssen Sie bei Änderungen an anderem Code neu erstellen?

Wenn Sie Dokumentation aus Quellcode generieren (z. B. API-Dokumentation aus Codekommentaren), lösen Sie über das Dashboard einen manuellen Build aus oder richten Sie einen Webhook in Ihrer CI-Pipeline ein.

Kompatibilität mit Workspace-Tools

Jamdesk funktioniert mit allen gängigen Monorepo-Tools. Über die Einstellung des Docs-Pfads hinaus ist keine spezielle Konfiguration erforderlich.

Tool	Unterstützt
npm workspaces	Ja
Yarn workspaces	Ja
pnpm workspaces	Ja
Turborepo	Ja
Nx	Ja
Lerna	Ja

Fehlerbehebung

Überprüfen Sie, ob der genaue Pfad in Ihrem Repository mit Ihrer Eingabe übereinstimmt
Stellen Sie sicher, dass docs.json an diesem Ort vorhanden ist
Prüfen Sie auf Tippfehler – bei Pfaden wird zwischen Groß- und Kleinschreibung unterschieden
Denken Sie daran: Verwenden Sie docs und nicht docs/docs.json

Schnellprüfung: In Ihrem Repository sollte die Datei unter [your-docs-path]/docs.json vorhanden sein

Asset-Pfade müssen relativ zu Ihrem Docs-Verzeichnis sein.

Korrekt – relativ zum Docs-Verzeichnis:

"favicon": "/images/favicon.svg"

Falsch – absolut vom Stammverzeichnis des Repositorys:

"favicon": "/packages/docs/images/favicon.svg"

Stellen Sie sicher, dass Ihre Bilder tatsächlich unter [docs-path]/images/ vorhanden sind.

Nur Änderungen innerhalb Ihres konfigurierten Docs-Pfads lösen automatische Builds aus.

Überprüfen Sie, ob Sie Dateien innerhalb des Docs-Pfads ändern
Prüfen Sie, ob Sie in den richtigen Branch pushen
Sehen Sie den Status der Webhook-Zustellung in den GitHub-Repository-Einstellungen ein

Wenn Builds durch Änderungen außerhalb des Docs-Pfads ausgelöst werden müssen, verwenden Sie manuelle Builds oder CI-Webhooks.

Wie geht es weiter?

GitHub verbinden

Verknüpfen Sie Ihr Repository für automatische Builds

Verzeichnisstruktur

Organisieren Sie Ihre Dokumentation für größere Projekte