Guida alla migrazione
Passi da un'altra piattaforma di documentazione? Jamdesk automatizza la transizione oppure puoi migrare manualmente per avere il pieno controllo.
I progetti Mintlify offrono un percorso con un solo comando: jamdesk migrate legge mint.json, scrive docs.json e riscrive l'MDX direttamente nei file. Provieni da GitBook, Docusaurus, ReadMe, Confluence o da un'altra piattaforma? La scheda "Altre piattaforme" illustra i passaggi manuali. Sono brevi se riesci a esportare i contenuti in Markdown.
Esporta prima in Markdown, se possibile. Jamdesk è basato su MDX, quindi tutto ciò che è già in Markdown può essere integrato rinominandolo con estensione .mdx e aggiungendo alcune righe di frontmatter.
Scegli il percorso
La CLI esegue automaticamente la maggior parte del lavoro.
Migrazione automatica
npm install -g jamdeskjamdesk migrateDalla radice del progetto, questo comando esegue in un unico passaggio le seguenti operazioni:
- Legge
mint.jsone scrivedocs.json - Rinomina i componenti deprecati nei file MDX (ad esempio
CardGroup→Columns) - Sposta i file MDX di snippet orfani in
/snippets/e riscrive ogni import relativo al percorso padre (../foo/bar.mdx) trasformandolo in un import relativo alla radice (/snippets/foo/bar.mdx) - Estrae i componenti inline che usano gli hook React in
/snippets/<name>.tsxcon la direttiva'use client', quindi riscrive l'MDX originale per importare da/snippets/ - Corregge automaticamente i problemi meccanici di sintassi MDX che causerebbero un errore nella build
Il comando è idempotente: eseguilo di nuovo dopo le modifiche e rileverà solo ciò che è nuovo. Tutto ciò che non può gestire automaticamente in modo sicuro viene stampato come avviso, con il file, l'import e l'azione da eseguire.
Controlla i file docs.json e MDX generati. Verifica la struttura della navigazione e gli eventuali avvisi stampati dalla CLI.
Mappatura della configurazione
La CLI converte automaticamente mint.json in docs.json. Queste sono le differenze principali per consentirti di 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> | Importa da /snippets/ | Approccio diverso |
Problemi comuni
jamdesk migrate rinomina CardGroup in Columns in tutti i file MDX. La prop cols viene mantenuta invariata. Controlla i file modificati dopo aver eseguito la migrazione.
Rinomina <ResponseField> in <ParamField>. Le prop restano invariate.
{/* 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 MDX degli snippet in qualsiasi punto dell'albero e li importano con percorsi relativi al padre (import X from '../shared/x.mdx').
jamdesk migrate esegue qui tre operazioni in un unico passaggio:
- Rileva i file MDX importati come snippet ma situati fuori da
/snippets/e li sposta in/snippets/, mantenendo il percorso relativo (in questo modo gli snippet con prefisso di locale comede/foo.mdxnon entrano in conflitto). - Riscrive ogni import di snippet relativo al padre in ogni file MDX nel nuovo percorso relativo alla radice.
- Estrae qualsiasi componente inline che usa gli hook React in un file
'use client'in/snippets/<name>.tsxe sostituisce l'export inline con un import da/snippets/.
Se hai usato l'elemento JSX <Snippet file="my-snippet.mdx" /> di Mintlify, sostituiscilo con un import MDX. Questo elemento non viene riscritto automaticamente:
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />
{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'
<MySnippet />Il relocator è prudente. Se il progetto non dispone di una navigazione risolta o gli spostamenti previsti superano max(5, 25%) di tutti i file MDX, interrompe l'operazione senza modificare nulla e ne spiega il motivo. Eseguilo di nuovo dopo aver risolto la causa dell'interruzione.
topbarLinks e topbarCtaButton di Mintlify vengono entrambi mappati su navbar.links in docs.json. Il campo name diventa label e url diventa href.