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

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.


  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.

<YouTube id="DvIHWeBliK0" />

<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://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.

    <Card title="HTML to MDX Converter" icon="file-code" href="https://jamdesk.com/utilities/html-to-mdx" horizontal>
      Exporting from a platform that gives you HTML (Confluence, Notion, and many others)? Paste it into the free HTML to MDX converter to get clean MDX you can drop straight into your project.
    </Card>

    <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>