Guida alla migrazione
Migra un progetto Mintlify con jamdesk migrate, che converte mint.json in docs.json e riscrive i tuoi file MDX sul posto.
Migra un progetto Mintlify con un solo comando: jamdesk migrate legge mint.json, scrive docs.json e riscrive il tuo MDX sul posto. Per GitBook, Docusaurus, ReadMe, Confluence o un'altra piattaforma, segui i passaggi manuali nella scheda "Altre piattaforme".
Esporta prima come Markdown, se possibile. Jamdesk è basato su MDX. Un file Markdown richiede solo la rinomina in .mdx e poche righe di frontmatter.
Scegli il percorso
Migrazione automatica
npm install -g jamdeskjamdesk migrateEseguilo dalla radice del progetto. Il comando fa quanto segue:
- Legge
mint.jsone scrivedocs.json - Rinomina i componenti deprecati nei file MDX (ad es.
CardGroup→Columns) - Sposta i file snippet MDX orfani in
/snippets/e riscrive ogni import relativo al genitore (../foo/bar.mdx) in uno relativo alla radice (/snippets/foo/bar.mdx) - Estrae i componenti inline che usano React hook in
/snippets/<name>.tsxcon la direttiva'use client'e riscrive l'MDX originale per importare da/snippets/ - Corregge automaticamente i problemi di sintassi MDX meccanici che causerebbero il crash della build
Il comando è idempotente. Eseguilo di nuovo dopo le modifiche per applicare solo le novità. Tutto ciò che non può essere corretto in sicurezza viene stampato come avviso con il file, l'import e l'azione da compiere.
Controlla il docs.json e i file MDX generati. Verifica la struttura di navigazione e correggi gli avvisi stampati dalla CLI.
Mappatura della configurazione
La CLI converte mint.json in docs.json. Usa queste differenze per verificare l'output.
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"] }
]
}
}Compatibilità dei componenti
La maggior parte dei componenti Mintlify ha un equivalente diretto in Jamdesk. Alcuni hanno nomi o sintassi diversi.
| Componente Mintlify | Equivalente Jamdesk | Note |
|---|---|---|
<Card> | <Card> | Stessa sintassi |
| CardGroup | <Columns> | Usa la prop cols per il numero di colonne |
<Columns> | <Columns> | Stessa sintassi |
<Accordion> | <Accordion> | Stessa sintassi |
<Tabs> / <Tab> | <Tabs> / <Tab> | Stessa sintassi |
<Steps> / <Step> | <Steps> / <Step> | Stessa sintassi |
<CodeGroup> | <CodeGroup> | Stessa sintassi |
<Tip>, <Note>, <Warning> | <Tip>, <Note>, <Warning> | Stessa sintassi |
<ResponseField> | <ParamField> | Nome diverso |
<Snippet> | Import da /snippets/ | Approccio diverso |
Problemi comuni
jamdesk migrate rinomina CardGroup in Columns in ogni file MDX. La prop cols viene mantenuta invariata. Controlla i file che hai modificato dopo aver eseguito la migrazione.
Rinomina <ResponseField> in <ParamField>. Le prop restano le stesse.
{/* Before */}
<ResponseField name="id" type="string" required>
The unique identifier
</ResponseField>
{/* After */}
<ParamField name="id" type="string" required>
The unique identifier
</ParamField>Jamdesk risolve solo gli import /snippets/* relativi alla radice. I progetti Mintlify spesso conservano i file snippet MDX in qualsiasi punto dell'albero e li importano con percorsi relativi al genitore (import X from '../shared/x.mdx').
jamdesk migrate risolve questo problema:
- Sposta in
/snippets/i file MDX importati come snippet ma che si trovano al di fuori di/snippets/. Mantiene il loro percorso relativo, così gli snippet con prefisso di locale comede/foo.mdxnon entrano in conflitto. - Riscrive ogni import di snippet relativo al genitore in ogni file MDX con il nuovo percorso relativo alla radice.
- Estrae qualsiasi componente inline che usa React hook in un file
'use client'in/snippets/<name>.tsxe sostituisce l'export inline con un import da/snippets/.
Sostituisci l'elemento JSX <Snippet file="my-snippet.mdx" /> di Mintlify con un import MDX. La CLI non lo riscrive:
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />
{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'
<MySnippet />Il relocator si interrompe senza toccare nulla se il progetto non ha una navigazione risolta o se gli spostamenti pianificati superano max(5, 25%) di tutti i file MDX. Stampa il motivo. Correggilo e riesegui.
topbarLinks e topbarCtaButton di Mintlify corrispondono a navbar.links in docs.json. Il campo name diventa label. Il campo url diventa href.