---
title: Migration Guide
description: Moving from another documentation platform? Jamdesk can help automate the transition, or you can migrate manually for full control.
---


  See the clean markdown version of this page at https://jamdesk.com/docs/setup/migration.md


Mintlify projects have a one-command path: `jamdesk migrate` reads `mint.json`, writes `docs.json`, and rewrites your MDX in place. Coming from GitBook, Docusaurus, ReadMe, Confluence, or somewhere else? The "Other Platforms" tab walks through the manual steps — they're short if you can get your content out as Markdown.

<Info>
**Export as Markdown first if you can.** Jamdesk is built on MDX, so anything already in Markdown drops in with a `.mdx` rename and a few lines of frontmatter.
</Info>

## Choose Your Path

<Tabs>
  <Tab title="From Mintlify">
    The CLI does the bulk of the work for you.

    <Card title="Mintlify to Jamdesk Guide" icon="book-open" href="https://www.jamdesk.com/blog/migrating-from-mintlify-to-jamdesk">
      Read the migration walkthrough with background, examples, and migration tips.
    </Card>

    ### Automated Migration

    <Steps>
      <Step title="Install the CLI">
        ```bash
        npm install -g jamdesk
        ```
      </Step>
      <Step title="Run the migration">
        ```bash
        jamdesk migrate
        ```

        From the project root, this runs in one pass:

        - Reads `mint.json` and writes `docs.json`
        - Renames deprecated components in MDX files (e.g. `CardGroup` → `Columns`)
        - Moves orphan snippet MDX files into `/snippets/` and rewrites every parent-relative import (`../foo/bar.mdx`) to a root-relative one (`/snippets/foo/bar.mdx`)
        - Extracts inline components that use React hooks into `/snippets/<name>.tsx` with the `'use client'` directive, then rewrites the original MDX to import from `/snippets/`
        - Auto-fixes mechanical MDX syntax issues that would crash the build

        The command is idempotent — re-run it after edits and it picks up only what's new. Anything it can't safely auto-handle is printed as a warning with the file, the import, and the action to take.
      </Step>
      <Step title="Review and adjust">
        Check the generated `docs.json` and MDX files. Verify navigation structure and any warnings printed by the CLI.
      </Step>
    </Steps>

    ### Configuration Mapping

    The CLI converts `mint.json` to `docs.json` automatically. These are the key differences so you can verify the output.

    **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"] }
        ]
      }
    }
    ```

    ### Component Compatibility

    Most Mintlify components have direct equivalents in Jamdesk. A few have different names or syntax.

    | Mintlify Component | Jamdesk Equivalent | Notes |
    |---|---|---|
    | `<Card>` | `<Card>` | Same syntax |
    | CardGroup | `<Columns>` | Use `cols` prop for column count |
    | `<Columns>` | `<Columns>` | Same syntax |
    | `<Accordion>` | `<Accordion>` | Same syntax |
    | `<Tabs>` / `<Tab>` | `<Tabs>` / `<Tab>` | Same syntax |
    | `<Steps>` / `<Step>` | `<Steps>` / `<Step>` | Same syntax |
    | `<CodeGroup>` | `<CodeGroup>` | Same syntax |
    | `<Tip>`, `<Note>`, `<Warning>` | `<Tip>`, `<Note>`, `<Warning>` | Same syntax |
    | `<ResponseField>` | `<ParamField>` | Different name |
    | `<Snippet>` | Import from `/snippets/` | Different approach |

    ### Common Issues

    <AccordionGroup>
      <Accordion title="CardGroup becomes Columns">
        `jamdesk migrate` renames `CardGroup` to `Columns` for you across every MDX file. The `cols` prop carries over unchanged. Check any files you've edited after running the migration.
      </Accordion>
      <Accordion title="ResponseField becomes ParamField">
        Rename `<ResponseField>` to `<ParamField>`. Props stay the same.

        ```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="Snippets are relocated and rewired automatically">
        Jamdesk resolves only root-relative `/snippets/*` imports. Mintlify projects often keep snippet MDX files anywhere in the tree and import them with parent-relative paths (`import X from '../shared/x.mdx'`).

        `jamdesk migrate` does three things here in one pass:

        - Detects MDX files that are imported as snippets but live outside `/snippets/`, and moves them under `/snippets/` while preserving their relative path (so locale-prefixed snippets like `de/foo.mdx` don't collide).
        - Rewrites every parent-relative snippet import in every MDX file to the new root-relative path.
        - Extracts any inline component that uses React hooks into a `'use client'` file at `/snippets/<name>.tsx` and replaces the inline export with an import from `/snippets/`.

        If you used Mintlify's `<Snippet file="my-snippet.mdx" />` JSX element, swap it for an MDX import — that one isn't auto-rewritten:

        ```mdx
        {/* Before (Mintlify) */}
        <Snippet file="my-snippet.mdx" />

        {/* After (Jamdesk) */}
        import MySnippet from '/snippets/my-snippet.mdx'

        <MySnippet />
        ```

        The relocator is conservative — if your project has no resolved navigation, or the planned moves exceed `max(5, 25%)` of all MDX files, it aborts without touching anything and tells you why. Re-run after fixing the abort reason.
      </Accordion>
      <Accordion title="topbarLinks maps to navbar.links">
        Mintlify's `topbarLinks` and `topbarCtaButton` both map to `navbar.links` in `docs.json`. The `name` field becomes `label`, and `url` becomes `href`.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="From Other Platforms">
    For GitBook, ReadMe, Docusaurus, Confluence, Notion, or other documentation tools.

    <Tip>
      Need help with your migration? [Let us know](mailto:contact@jamdesk.com) and we'll get you set up.
    </Tip>

    ### From GitBook

    GitBook stores content as Markdown with a `SUMMARY.md` file for navigation.

    <Steps>
      <Step title="Export your content">
        Export your GitBook space as Markdown. If you're using GitBook's Git sync, your content is already in a Git repo as `.md` files.
      </Step>
      <Step title="Convert files to MDX">
        Rename `.md` files to `.mdx` and add frontmatter to each file:

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

        Your existing Markdown content here.
        ```
      </Step>
      <Step title="Map navigation from SUMMARY.md">
        GitBook uses `SUMMARY.md` to define its sidebar. Convert this to `docs.json` navigation groups.

        **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="Move images">
        Move all images to an `/images` directory and update references in your MDX files to use absolute paths (e.g., `/images/screenshot.png`).
      </Step>
      <Step title="Test locally">
        ```bash
        jamdesk dev
        ```
      </Step>
    </Steps>

    ### From Docusaurus

    Docusaurus projects already use MDX, so most content transfers directly.

    <Steps>
      <Step title="Copy your MDX files">
        Copy the contents of your Docusaurus `docs/` directory into your Jamdesk project root. Keep your existing directory structure.
      </Step>
      <Step title="Clean up frontmatter">
        Remove Docusaurus-specific frontmatter fields. Keep `title` and `description`, drop the rest.

        ```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="Map sidebars.js to docs.json">
        Convert your `sidebars.js` category structure to `docs.json` navigation groups.

        **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="Replace Docusaurus components">
        Swap Docusaurus-specific components for Jamdesk equivalents.

        | Docusaurus | Jamdesk | Example |
        |---|---|---|
        | `:::note` / `:::tip` / `:::warning` | `<Note>` / `<Tip>` / `<Warning>` | See [callout components](/components/overview) |
        | `import Tabs from '@theme/Tabs'` | `<Tabs>` (globally available) | No import needed |
        | `import TabItem from '@theme/TabItem'` | `<Tab>` (globally available) | Use `title` instead of `label` |
      </Step>
      <Step title="Test locally">
        ```bash
        jamdesk dev
        ```
      </Step>
    </Steps>

    ### From Other Tools

    For Confluence, Notion, ReadMe, or any other platform, the process is the same: get your content into Markdown, then set up the Jamdesk project structure.

    <Steps>
      <Step title="Export as Markdown">
        Most platforms have a Markdown or HTML export option. Use Markdown if available. For HTML, convert to Markdown using a tool like [Pandoc](https://pandoc.org/).

        ```bash
        # Convert HTML to Markdown with Pandoc
        pandoc input.html -f html -t markdown -o output.md
        ```
      </Step>
      <Step title="Create docs.json">
        Start with a minimal configuration and build out your navigation as you add pages.
      </Step>
      <Step title="Convert files to MDX">
        Rename `.md` files to `.mdx` and add frontmatter (`title`, `description`) to each file.
      </Step>
      <Step title="Move assets">
        Move images and other assets to an `/images` directory. Update file references to use absolute paths.
      </Step>
      <Step title="Test locally">
        ```bash
        jamdesk dev
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Post-Migration Checklist

<Check>All pages render without errors</Check>
<Check>Navigation structure matches your original site</Check>
<Check>Internal links work correctly</Check>
<Check>Images and assets display properly</Check>
<Check>Code blocks have correct syntax highlighting</Check>
<Check>Search indexes your content</Check>

## What's Next?

<Columns cols={2}>
  <Card title="Directory Structure" icon="folder-tree" href="/setup/directory-structure">
    Learn how to organize your documentation
  </Card>
  <Card title="docs.json Reference" icon="gear" href="/config/docs-json-reference">
    Configure your site settings
  </Card>
</Columns>