Migrationsleitfaden
Wechseln Sie von einer anderen Dokumentationsplattform? Jamdesk unterstützt die automatische oder manuelle Migration mit voller Kontrolle.
Mintlify-Projekte bieten einen Pfad mit einem einzigen Befehl: jamdesk migrate liest mint.json, schreibt docs.json und schreibt Ihr MDX direkt um. Wechseln Sie von GitBook, Docusaurus, ReadMe, Confluence oder einer anderen Plattform? Der Tab „Andere Plattformen“ führt durch die manuellen Schritte. Diese sind kurz, wenn Sie Ihre Inhalte als Markdown exportieren können.
Exportieren Sie zuerst als Markdown, wenn möglich. Jamdesk basiert auf MDX. Alles, was bereits als Markdown vorliegt, kann mit einer Umbenennung in .mdx und einigen Frontmatter-Zeilen übernommen werden.
Wählen Sie Ihren Pfad
Die CLI übernimmt den größten Teil der Arbeit für Sie.
Automatische Migration
npm install -g jamdeskjamdesk migrateVom Projektstamm aus führt dieser Befehl Folgendes in einem Durchlauf aus:
- Liest
mint.jsonund schreibtdocs.json - Benennt veraltete Komponenten in MDX-Dateien um (z. B.
CardGroup→Columns) - Verschiebt verwaiste MDX-Snippet-Dateien nach
/snippets/und schreibt alle übergeordneten relativen Imports (../foo/bar.mdx) in stammrelative Imports (/snippets/foo/bar.mdx) um - Extrahiert Inline-Komponenten, die React-Hooks verwenden, mit der Direktive
'use client'nach/snippets/<name>.tsxund schreibt das ursprüngliche MDX so um, dass es aus/snippets/importiert - Behebt automatisch mechanische MDX-Syntaxprobleme, die den Build zum Absturz bringen würden
Der Befehl ist idempotent: Führen Sie ihn nach Änderungen erneut aus, werden nur neue Änderungen übernommen. Alles, was nicht sicher automatisch verarbeitet werden kann, wird als Warnung mit der Datei, dem Import und der erforderlichen Aktion ausgegeben.
Prüfen Sie die generierten Dateien docs.json und MDX. Überprüfen Sie die Navigationsstruktur und alle von der CLI ausgegebenen Warnungen.
Konfigurationszuordnung
Die CLI konvertiert mint.json automatisch in docs.json. Dies sind die wichtigsten Unterschiede, anhand derer Sie die Ausgabe überprüfen können.
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"] }
]
}
}Kompatibilität der Komponenten
Die meisten Mintlify-Komponenten haben direkte Entsprechungen in Jamdesk. Einige unterscheiden sich jedoch bei Namen oder Syntax.
| Mintlify-Komponente | Jamdesk-Entsprechung | Hinweise |
|---|---|---|
<Card> | <Card> | Gleiche Syntax |
| CardGroup | <Columns> | Verwenden Sie die Prop cols für die Spaltenanzahl |
<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/ | Anderer Ansatz |
Häufige Probleme
jamdesk migrate benennt CardGroup in allen MDX-Dateien für Sie in Columns um. Die Prop cols wird unverändert übernommen. Überprüfen Sie alle Dateien, die Sie nach der Migration bearbeitet haben.
Benennen Sie <ResponseField> in <ParamField> um. Die Props bleiben unverändert.
{/* 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 stammrelative /snippets/*-Imports auf. Mintlify-Projekte speichern MDX-Snippet-Dateien häufig an beliebigen Stellen im Verzeichnisbaum und importieren sie mit übergeordneten relativen Pfaden (import X from '../shared/x.mdx').
jamdesk migrate führt hier in einem Durchlauf drei Aktionen aus:
- Erkennt MDX-Dateien, die als Snippets importiert werden, aber außerhalb von
/snippets/liegen, und verschiebt sie unter/snippets/, wobei ihr relativer Pfad erhalten bleibt (damit Snippets mit vorangestellter Sprachkennung wiede/foo.mdxnicht kollidieren). - Schreibt jeden übergeordneten relativen Snippet-Import in jeder MDX-Datei in den neuen stammrelativen Pfad um.
- Extrahiert jede Inline-Komponente, die React-Hooks verwendet, in eine
'use client'-Datei unter/snippets/<name>.tsxund ersetzt den Inline-Export durch einen Import aus/snippets/.
Wenn Sie das Mintlify-JSX-Element <Snippet file="my-snippet.mdx" /> verwendet haben, ersetzen Sie es durch einen MDX-Import. Dieses Element wird nicht automatisch umgeschrieben:
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />
{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'
<MySnippet />Das Verschieben ist konservativ. Wenn Ihr Projekt keine aufgelöste Navigation besitzt oder die geplanten Verschiebungen max(5, 25%) aller MDX-Dateien überschreiten, wird der Vorgang abgebrochen, ohne Änderungen vorzunehmen, und der Grund ausgegeben. Führen Sie den Befehl nach Behebung des Abbruchgrunds erneut aus.
Sowohl topbarLinks als auch topbarCtaButton von Mintlify werden in docs.json navbar.links zugeordnet. Das Feld name wird zu label, und url wird zu href.