Jamdesk Documentation logo

Migrationsleitfaden

Migriere ein Mintlify-Projekt mit jamdesk migrate: Der Befehl wandelt mint.json in docs.json um und schreibt deine MDX-Dateien direkt um.

Migriere ein Mintlify-Projekt mit einem Befehl: jamdesk migrate liest mint.json, schreibt docs.json und schreibt deine MDX-Dateien direkt um. Für GitBook, Docusaurus, ReadMe, Confluence oder eine andere Plattform folge den manuellen Schritten im Tab „Von anderen Plattformen“.

Exportiere die Inhalte zuerst als Markdown, wenn möglich. Jamdesk basiert auf MDX. Eine Markdown-Datei muss nur in .mdx umbenannt werden und einige Zeilen Frontmatter erhalten.

Wählen Sie Ihren Pfad

Mintlify-zu-Jamdesk-Leitfaden

Migrationsanleitung mit Hintergrundinformationen, Beispielen und Tipps.

Automatische Migration

1
CLI installieren
npm install -g jamdesk
2
Migration ausführen
jamdesk migrate

Führe den Befehl im Projektstammverzeichnis aus. Er erledigt Folgendes:

  • Liest mint.json und schreibt docs.json
  • Benennt veraltete Komponenten in MDX-Dateien um (z. B. CardGroup → Columns)
  • Verschiebt verwaiste MDX-Snippet-Dateien nach /snippets/ und schreibt alle relativen Imports mit ../ auf root-relative Imports um (../foo/bar.mdx wird zu /snippets/foo/bar.mdx)
  • Extrahiert Inline-Komponenten mit React Hooks nach /snippets/<name>.tsx, ergänzt die Direktive 'use client' und ändert den ursprünglichen MDX-Import so, dass er aus /snippets/ importiert
  • Behebt automatisch mechanische MDX-Syntaxprobleme, die den Build zum Absturz bringen würden

Der Befehl ist idempotent. Führe ihn nach Änderungen erneut aus, um nur neue Inhalte zu erfassen. Alles, was sich nicht sicher beheben lässt, wird als Warnung mit Datei, Import und erforderlicher Maßnahme ausgegeben.

3
Prüfen und anpassen

Prüfe die erzeugten Dateien docs.json und MDX. Überprüfe die Navigationsstruktur und behebe alle von der CLI ausgegebenen Warnungen.

Konfigurationszuordnung

Die CLI konvertiert mint.json in docs.json. Prüfe die Ausgabe anhand dieser Unterschiede.

Mintlify (mint.json):

{
  "name": "My Docs",
  "navigation": [
    { "group": "Getting Started", "pages": ["introduction", "quickstart"] }
  ],
  "colors": { "primary": "#0D9373" },
  "topbarLinks": [{ "name": "Blog", "url": "https://example.com/blog" }]
}

Jamdesk (docs.json):

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "My Docs",
  "theme": "jam",
  "colors": { "primary": "#0D9373" },
  "navbar": {
    "links": [{ "label": "Blog", "href": "https://example.com/blog" }]
  },
  "navigation": {
    "groups": [
      { "group": "Getting Started", "pages": ["introduction", "quickstart"] }
    ]
  }
}

Komponentenkompatibilität

Die meisten Mintlify-Komponenten haben direkte Jamdesk-Entsprechungen. Einige haben andere Namen oder Syntax.

Mintlify-KomponenteJamdesk-EntsprechungHinweise
<Card><Card>Gleiche Syntax
CardGroup<Columns>Verwende die Prop cols, um die Spaltenanzahl festzulegen
<Columns><Columns>Gleiche Syntax
<Accordion><Accordion>Gleiche Syntax
<Tabs> / <Tab><Tabs> / <Tab>Gleiche Syntax
<Steps> / <Step><Steps> / <Step>Gleiche Syntax
<CodeGroup><CodeGroup>Gleiche Syntax
<Tip>, <Note>, <Warning><Tip>, <Note>, <Warning>Gleiche Syntax
<ResponseField><ParamField>Anderer Name
<Snippet>Import aus /snippets/Andere Vorgehensweise

Häufige Probleme

jamdesk migrate benennt CardGroup in jeder MDX-Datei in Columns um. Die Prop cols bleibt unverändert erhalten. Prüfe alle Dateien, die du nach der Migration bearbeitet hast.

Benenne <ResponseField> in <ParamField> um. Die Props bleiben gleich.

{/* Before */}
<ResponseField name="id" type="string" required>
  The unique identifier
</ResponseField>

{/* After */}
<ParamField name="id" type="string" required>
  The unique identifier
</ParamField>

Jamdesk löst nur root-relative /snippets/*-Imports auf. In Mintlify-Projekten liegen MDX-Snippet-Dateien oft an beliebigen Stellen in der Verzeichnisstruktur und werden über relative Pfade mit ../ importiert (import X from '../shared/x.mdx').

jamdesk migrate behebt das:

  • Verschiebt MDX-Dateien, die als Snippets importiert werden, aber außerhalb von /snippets/ liegen, nach /snippets/. Der relative Pfad bleibt erhalten, damit Snippets mit Locale-Präfix wie de/foo.mdx nicht kollidieren.
  • Schreibt alle relativen Snippet-Imports mit ../ in sämtlichen MDX-Dateien auf den neuen root-relativen Pfad um.
  • Extrahiert jede Inline-Komponente mit React Hooks in eine Datei mit 'use client' unter /snippets/<name>.tsx und ersetzt den Inline-Export durch einen Import aus /snippets/.

Ersetze das JSX-Element <Snippet file="my-snippet.mdx" /> von Mintlify durch einen MDX-Import. Die CLI schreibt es nicht um:

{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />

{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'

<MySnippet />

Der Verschiebevorgang wird abgebrochen, ohne Änderungen vorzunehmen, wenn dein Projekt keine aufgelöste Navigation hat oder die geplanten Verschiebungen mehr als max(5, 25%) aller MDX-Dateien betreffen. Der Grund wird ausgegeben. Behebe das Problem und führe den Befehl erneut aus.

Mintlifys topbarLinks und topbarCtaButton werden in docs.json navbar.links zugeordnet. Das Feld name wird zu label. Das Feld url wird zu href.

Checkliste nach der Migration

Alle Seiten werden fehlerfrei dargestellt
Die Navigationsstruktur entspricht der ursprünglichen Website
Interne Links funktionieren korrekt
Bilder und Assets werden richtig angezeigt
Codeblöcke verwenden die korrekte Syntaxhervorhebung
Die Suche indexiert deine Inhalte

Wie geht es weiter?

Verzeichnisstruktur

Erfahre, wie du deine Dokumentation organisierst

docs.json-Referenz

Konfiguriere die Einstellungen deiner Website