Guide de migration
Vous migrez depuis une autre plateforme de documentation ? Jamdesk peut automatiser la transition, ou vous pouvez migrer manuellement pour un contrôle total.
Les projets Mintlify disposent d'un chemin en une seule commande : jamdesk migrate lit mint.json, génère docs.json et réécrit vos fichiers MDX sur place. Vous venez de GitBook, Docusaurus, ReadMe, Confluence ou d'une autre plateforme ? L'onglet "Autres plateformes" détaille les étapes manuelles — elles sont courtes si vous pouvez exporter votre contenu en Markdown.
Exportez en Markdown en premier si possible. Jamdesk est construit sur MDX, donc tout contenu déjà en Markdown s'intègre facilement avec un renommage en .mdx et quelques lignes de frontmatter.
Choisissez votre chemin
Le CLI effectue l'essentiel du travail à votre place.
Migration automatisée
npm install -g jamdeskjamdesk migrateDepuis la racine du projet, cette commande s'exécute en une seule passe :
- Lit
mint.jsonet génèredocs.json - Renomme les composants obsolètes dans les fichiers MDX (ex.
CardGroup→Columns) - Déplace les fichiers MDX de snippets orphelins dans
/snippets/et réécrit chaque import relatif au parent (../foo/bar.mdx) en import relatif à la racine (/snippets/foo/bar.mdx) - Extrait les composants inline utilisant des hooks React dans
/snippets/<name>.tsxavec la directive'use client', puis réécrit le MDX d'origine pour importer depuis/snippets/ - Corrige automatiquement les problèmes de syntaxe MDX mécaniques qui provoqueraient un échec du build
La commande est idempotente — relancez-la après des modifications et elle ne traite que ce qui est nouveau. Tout ce qu'elle ne peut pas gérer automatiquement en toute sécurité est affiché sous forme d'avertissement avec le fichier, l'import et l'action à effectuer.
Contrôlez le docs.json généré et les fichiers MDX. Vérifiez la structure de navigation et les éventuels avertissements affichés par le CLI.
Correspondance de configuration
Le CLI convertit automatiquement mint.json en docs.json. Voici les différences clés pour vous permettre de vérifier le résultat.
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é des composants
La plupart des composants Mintlify ont des équivalents directs dans Jamdesk. Quelques-uns ont des noms ou une syntaxe différents.
| Composant Mintlify | Équivalent Jamdesk | Notes |
|---|---|---|
<Card> | <Card> | Même syntaxe |
| CardGroup | <Columns> | Utilisez la prop cols pour le nombre de colonnes |
<Columns> | <Columns> | Même syntaxe |
<Accordion> | <Accordion> | Même syntaxe |
<Tabs> / <Tab> | <Tabs> / <Tab> | Même syntaxe |
<Steps> / <Step> | <Steps> / <Step> | Même syntaxe |
<CodeGroup> | <CodeGroup> | Même syntaxe |
<Tip>, <Note>, <Warning> | <Tip>, <Note>, <Warning> | Même syntaxe |
<ResponseField> | <ParamField> | Nom différent |
<Snippet> | Import depuis /snippets/ | Approche différente |
Problèmes courants
jamdesk migrate renomme CardGroup en Columns dans tous vos fichiers MDX. La prop cols est conservée telle quelle. Vérifiez les fichiers que vous avez modifiés après avoir exécuté la migration.
Renommez <ResponseField> en <ParamField>. Les props restent identiques.
{/* Before */}
<ResponseField name="id" type="string" required>
The unique identifier
</ResponseField>
{/* After */}
<ParamField name="id" type="string" required>
The unique identifier
</ParamField>Jamdesk ne résout que les imports /snippets/* relatifs à la racine. Les projets Mintlify gardent souvent les fichiers MDX de snippets n'importe où dans l'arborescence et les importent avec des chemins relatifs au parent (import X from '../shared/x.mdx').
jamdesk migrate effectue trois opérations en une seule passe :
- Détecte les fichiers MDX importés comme snippets mais situés hors de
/snippets/, et les déplace sous/snippets/en préservant leur chemin relatif (afin que les snippets préfixés par une locale commede/foo.mdxn'entrent pas en collision). - Réécrit chaque import de snippet relatif au parent dans chaque fichier MDX vers le nouveau chemin relatif à la racine.
- Extrait tout composant inline utilisant des hooks React dans un fichier
'use client'à/snippets/<name>.tsxet remplace l'export inline par un import depuis/snippets/.
Si vous utilisiez l'élément JSX <Snippet file="my-snippet.mdx" /> de Mintlify, remplacez-le par un import MDX — celui-ci n'est pas réécrit automatiquement :
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />
{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'
<MySnippet />Le déplaceur est conservateur — si votre projet n'a pas de navigation résolue, ou si les déplacements prévus dépassent max(5, 25%) de tous les fichiers MDX, il s'arrête sans rien modifier et vous explique pourquoi. Relancez après avoir corrigé la cause de l'arrêt.
Les champs topbarLinks et topbarCtaButton de Mintlify correspondent tous deux à navbar.links dans docs.json. Le champ name devient label, et url devient href.