Guide de migration
Vous passez d'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 commande : jamdesk migrate lit mint.json, écrit docs.json, et réécrit votre MDX sur place. Vous venez de GitBook, Docusaurus, ReadMe, Confluence, ou d'ailleurs ? L'onglet « Autres plateformes » détaille les étapes manuelles. Elles sont courtes si vous pouvez extraire votre contenu en Markdown.
Exportez d'abord en Markdown si possible. Jamdesk est construit sur MDX, donc tout ce qui est déjà en Markdown s'intègre avec un renommage en .mdx et quelques lignes de frontmatter.
Choisissez votre chemin
Le CLI effectue la majeure partie du travail pour vous.
Migration automatisée
npm install -g jamdeskjamdesk migrateDepuis la racine du projet, ceci s'exécute en une seule passe :
- Lit
mint.jsonet écritdocs.json - Renomme les composants dépréciés dans les fichiers MDX (par ex.
CardGroup→Columns) - Déplace les fichiers MDX de snippets orphelins vers
/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 en ligne qui utilisent des hooks React vers
/snippets/<name>.tsxavec la directive'use client', puis réécrit le MDX original pour importer depuis/snippets/ - Corrige automatiquement les problèmes mécaniques de syntaxe MDX qui feraient échouer le 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é comme avertissement avec le fichier, l'import, et l'action à entreprendre.
Vérifiez le docs.json généré et les fichiers MDX. Vérifiez la structure de navigation et tout avertissement affiché par le CLI.
Correspondance de configuration
Le CLI convertit mint.json en docs.json automatiquement. Voici les différences clés pour que vous puissiez 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> | Syntaxe identique |
| CardGroup | <Columns> | Utilisez la prop cols pour le nombre de colonnes |
<Columns> | <Columns> | Syntaxe identique |
<Accordion> | <Accordion> | Syntaxe identique |
<Tabs> / <Tab> | <Tabs> / <Tab> | Syntaxe identique |
<Steps> / <Step> | <Steps> / <Step> | Syntaxe identique |
<CodeGroup> | <CodeGroup> | Syntaxe identique |
<Tip>, <Note>, <Warning> | <Tip>, <Note>, <Warning> | Syntaxe identique |
<ResponseField> | <ParamField> | Nom différent |
<Snippet> | Import depuis /snippets/ | Approche différente |
Problèmes courants
jamdesk migrate renomme CardGroup en Columns pour vous dans tous les fichiers 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 conservent 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 actions ici en une seule passe :
- Détecte les fichiers MDX importés comme snippets mais situés en dehors de
/snippets/, et les déplace sous/snippets/en préservant leur chemin relatif (pour 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 en ligne qui utilise des hooks React vers un fichier
'use client'à/snippets/<name>.tsxet remplace l'export en ligne 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-là n'est pas réécrit automatiquement :
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />
{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'
<MySnippet />Le relocalisateur est prudent. 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'interrompt sans rien toucher et vous indique pourquoi. Relancez après avoir corrigé la cause de l'interruption.
topbarLinks et topbarCtaButton de Mintlify correspondent tous deux à navbar.links dans docs.json. Le champ name devient label, et url devient href.