Guide de migration
Vous migrez depuis une autre plateforme de documentation ? Jamdesk peut automatiser la transition ou vous pouvez migrer manuellement.
Les projets Mintlify disposent d'un chemin en une seule commande : jamdesk migrate lit mint.json, écrit docs.json et réécrit vos fichiers MDX en place. Vous venez de GitBook, Docusaurus, ReadMe, Confluence ou d'ailleurs ? L'onglet "Autres plateformes" décrit les étapes manuelles — elles sont courtes si vous pouvez exporter votre contenu en Markdown.
Exportez d'abord en Markdown si possible. Jamdesk est construit sur MDX, donc tout contenu déjà en Markdown s'intègre directement avec un renommage en .mdx et quelques lignes de frontmatter.
Choisissez votre chemin
Le CLI fait l'essentiel du travail pour vous.
Migration automatisée
npm install -g jamdeskjamdesk migrateDepuis la racine du projet, cette commande s'exécute en une seule passe :
- Lit
mint.jsonet écritdocs.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 un 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 original pour importer depuis/snippets/ - Corrige automatiquement les problèmes de syntaxe MDX mécaniques qui planteraient le build
La commande est idempotente — relancez-la après des modifications et elle ne traite que les nouveaux éléments. Tout ce qu'elle ne peut pas gérer automatiquement est affiché comme un avertissement avec le fichier, l'import et l'action à effectuer.
Vérifiez le fichier docs.json généré et les fichiers MDX. Contrôlez la structure de navigation et les éventuels avertissements affichés par le CLI.
Correspondance de configuration
Le CLI convertit mint.json en docs.json automatiquement. 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 chaque fichier MDX. La prop cols est conservée telle quelle. Vérifiez les fichiers que vous avez modifiés après avoir lancé 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 résout uniquement 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/, les déplace sous/snippets/en préservant leur chemin relatif (afin que les snippets préfixés par langue 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 toucher et vous indique 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.