---
title: Guide de migration
description: Vous migrez depuis une autre plateforme de documentation ? Jamdesk peut automatiser la transition, ou vous pouvez migrer manuellement pour un contrôle total.
---


  Consultez la version Markdown propre de cette page à l'adresse https://jamdesk.com/docs/setup/migration.md


Les projets Mintlify disposent d'un chemin en une seule commande : `jamdesk migrate` lit `mint.json`, écrit `docs.json` et réécrit votre MDX en 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.

<Info>
**Exportez d'abord en Markdown si possible.** Jamdesk est construit sur MDX, donc tout contenu déjà en Markdown s'intègre avec un simple renommage en `.mdx` et quelques lignes de frontmatter.
</Info>

## Choisissez votre chemin

<Tabs>
  <Tab title="Depuis Mintlify">
    Le CLI fait l'essentiel du travail à votre place.

    <Card title="Guide de migration Mintlify vers Jamdesk" icon="book-open" href="https://www.jamdesk.com/blog/migrating-from-mintlify-to-jamdesk">
      Lisez le guide de migration complet avec contexte, exemples et conseils.
    </Card>

    ### Migration automatisée

    <Steps>
      <Step title="Installer le CLI">
        ```bash
        npm install -g jamdesk
        ```
      </Step>
      <Step title="Lancer la migration">
        ```bash
        jamdesk migrate
        ```

        Depuis la racine du projet, cette commande s'exécute en une seule passe :

        - Lit `mint.json` et écrit `docs.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 vers `/snippets/<name>.tsx` avec la directive `'use client'`, puis réécrit le MDX d'origine pour importer depuis `/snippets/`
        - Corrige automatiquement les problèmes syntaxiques MDX mécaniques qui feraient planter le build

        La commande est idempotente — relancez-la après des modifications et elle ne traite que les nouveautés. Tout ce qu'elle ne peut pas gérer en toute sécurité est affiché comme avertissement avec le fichier, l'import et l'action à effectuer.
      </Step>
      <Step title="Vérifier et ajuster">
        Contrôlez le fichier `docs.json` généré et les fichiers MDX. Vérifiez la structure de navigation et les avertissements affichés par le CLI.
      </Step>
    </Steps>

    ### Correspondance de configuration

    Le CLI convertit automatiquement `mint.json` en `docs.json`. Voici les principales différences pour vous permettre de vérifier le résultat.

    **Mintlify (`mint.json`) :**
    ```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`) :**
    ```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

    <AccordionGroup>
      <Accordion title="CardGroup devient Columns">
        `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 lancé la migration.
      </Accordion>
      <Accordion title="ResponseField devient ParamField">
        Renommez `<ResponseField>` en `<ParamField>`. Les props restent identiques.

        ```mdx
        {/* Before */}
        <ResponseField name="id" type="string" required>
          The unique identifier
        </ResponseField>

        {/* After */}
        <ParamField name="id" type="string" required>
          The unique identifier
        </ParamField>
        ```
      </Accordion>
      <Accordion title="Les snippets sont déplacés et recâblés automatiquement">
        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 locale comme `de/foo.mdx` n'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 vers un fichier `'use client'` dans `/snippets/<name>.tsx` et 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 :

        ```mdx
        {/* 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 planifiés 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.
      </Accordion>
      <Accordion title="topbarLinks correspond à navbar.links">
        Les champs `topbarLinks` et `topbarCtaButton` de Mintlify correspondent tous deux à `navbar.links` dans `docs.json`. Le champ `name` devient `label`, et `url` devient `href`.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Autres plateformes">
    Pour GitBook, ReadMe, Docusaurus, Confluence, Notion ou d'autres outils de documentation.

    <Tip>
      Besoin d'aide pour votre migration ? [Contactez-nous](mailto:contact@jamdesk.com) et nous vous accompagnerons.
    </Tip>

    ### Depuis GitBook

    GitBook stocke le contenu en Markdown avec un fichier `SUMMARY.md` pour la navigation.

    <Steps>
      <Step title="Exporter votre contenu">
        Exportez votre espace GitBook en Markdown. Si vous utilisez la synchronisation Git de GitBook, votre contenu est déjà dans un dépôt Git sous forme de fichiers `.md`.
      </Step>
      <Step title="Convertir les fichiers en MDX">
        Renommez les fichiers `.md` en `.mdx` et ajoutez un frontmatter à chaque fichier :

        ```mdx
        ---
        title: Your Page Title
        description: A short description of the page
        ---

        Your existing Markdown content here.
        ```
      </Step>
      <Step title="Mapper la navigation depuis SUMMARY.md">
        GitBook utilise `SUMMARY.md` pour définir sa barre latérale. Convertissez-la en groupes de navigation `docs.json`.

        **GitBook (`SUMMARY.md`) :**
        ```markdown
        # Summary

        ## Getting Started
        * [Introduction](introduction.md)
        * [Quick Start](quickstart.md)

        ## API Reference
        * [Authentication](api/auth.md)
        ```

        **Jamdesk (`docs.json`) :**
        ```json
        {
          "navigation": {
            "groups": [
              {
                "group": "Getting Started",
                "pages": ["introduction", "quickstart"]
              },
              {
                "group": "API Reference",
                "pages": ["api/auth"]
              }
            ]
          }
        }
        ```
      </Step>
      <Step title="Déplacer les images">
        Déplacez toutes les images dans un répertoire `/images` et mettez à jour les références dans vos fichiers MDX pour utiliser des chemins absolus (ex. `/images/screenshot.png`).
      </Step>
      <Step title="Tester en local">
        ```bash
        jamdesk dev
        ```
      </Step>
    </Steps>

    ### Depuis Docusaurus

    Les projets Docusaurus utilisent déjà MDX, donc la plupart du contenu se transfère directement.

    <Steps>
      <Step title="Copier vos fichiers MDX">
        Copiez le contenu de votre répertoire `docs/` Docusaurus dans la racine de votre projet Jamdesk. Conservez votre structure de répertoires existante.
      </Step>
      <Step title="Nettoyer le frontmatter">
        Supprimez les champs de frontmatter spécifiques à Docusaurus. Conservez `title` et `description`, supprimez le reste.

        ```yaml
        ---
        # Remove these Docusaurus fields
        sidebar_position: 3
        sidebar_label: "Custom Label"
        slug: /custom-url
        pagination_next: null

        # Keep these
        title: Your Page Title
        description: A short description
        ---
        ```
      </Step>
      <Step title="Mapper sidebars.js vers docs.json">
        Convertissez la structure de catégories de votre `sidebars.js` en groupes de navigation `docs.json`.

        **Docusaurus (`sidebars.js`) :**
        ```javascript
        module.exports = {
          docs: [
            {
              type: 'category',
              label: 'Getting Started',
              items: ['intro', 'installation'],
            },
          ],
        };
        ```

        **Jamdesk (`docs.json`) :**
        ```json
        {
          "navigation": {
            "groups": [
              {
                "group": "Getting Started",
                "pages": ["intro", "installation"]
              }
            ]
          }
        }
        ```
      </Step>
      <Step title="Remplacer les composants Docusaurus">
        Remplacez les composants spécifiques à Docusaurus par leurs équivalents Jamdesk.

        | Docusaurus | Jamdesk | Exemple |
        |---|---|---|
        | `:::note` / `:::tip` / `:::warning` | `<Note>` / `<Tip>` / `<Warning>` | Voir [composants callout](/fr/components/overview) |
        | `import Tabs from '@theme/Tabs'` | `<Tabs>` (disponible globalement) | Aucun import nécessaire |
        | `import TabItem from '@theme/TabItem'` | `<Tab>` (disponible globalement) | Utilisez `title` plutôt que `label` |
      </Step>
      <Step title="Tester en local">
        ```bash
        jamdesk dev
        ```
      </Step>
    </Steps>

    ### Depuis d'autres outils

    Pour Confluence, Notion, ReadMe ou toute autre plateforme, le processus est identique : exportez votre contenu en Markdown, puis configurez la structure du projet Jamdesk.

    <Steps>
      <Step title="Exporter en Markdown">
        La plupart des plateformes proposent une option d'export Markdown ou HTML. Utilisez Markdown si disponible. Pour HTML, convertissez en Markdown avec un outil comme [Pandoc](https://pandoc.org/).

        ```bash
        # Convert HTML to Markdown with Pandoc
        pandoc input.html -f html -t markdown -o output.md
        ```
      </Step>
      <Step title="Créer docs.json">
        Commencez par une configuration minimale et construisez votre navigation au fur et à mesure que vous ajoutez des pages.
      </Step>
      <Step title="Convertir les fichiers en MDX">
        Renommez les fichiers `.md` en `.mdx` et ajoutez un frontmatter (`title`, `description`) à chaque fichier.
      </Step>
      <Step title="Déplacer les assets">
        Déplacez les images et autres assets dans un répertoire `/images`. Mettez à jour les références de fichiers pour utiliser des chemins absolus.
      </Step>
      <Step title="Tester en local">
        ```bash
        jamdesk dev
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Liste de contrôle post-migration

<Check>Toutes les pages s'affichent sans erreur</Check>
<Check>La structure de navigation correspond à votre site d'origine</Check>
<Check>Les liens internes fonctionnent correctement</Check>
<Check>Les images et assets s'affichent correctement</Check>
<Check>Les blocs de code ont la coloration syntaxique appropriée</Check>
<Check>La recherche indexe votre contenu</Check>

## Et ensuite ?

<Columns cols={2}>
  <Card title="Structure des répertoires" icon="folder-tree" href="/fr/setup/directory-structure">
    Apprenez à organiser votre documentation
  </Card>
  <Card title="Référence docs.json" icon="gear" href="/fr/config/docs-json-reference">
    Configurez les paramètres de votre site
  </Card>
</Columns>