Migration Guide
Migrate a Mintlify project with jamdesk migrate, which converts mint.json to docs.json and rewrites your MDX files in place.
Migrate a Mintlify project with one command: jamdesk migrate reads mint.json, writes docs.json, and rewrites your MDX in place. For GitBook, Docusaurus, ReadMe, Confluence, or another platform, follow the manual steps in the "Other Platforms" tab.
Export as Markdown first if you can. Jamdesk is built on MDX. A Markdown file needs only a .mdx rename and a few lines of frontmatter.
Choose Your Path
Automated Migration
npm install -g jamdeskjamdesk migrateRun it from the project root. It does the following:
- Reads
mint.jsonand writesdocs.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>.tsxwith the'use client'directive and 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 to pick up only what's new. Anything it can't safely fix prints as a warning with the file, the import, and the action to take.
Check the generated docs.json and MDX files. Verify the navigation structure and fix any warnings printed by the CLI.
Configuration Mapping
The CLI converts mint.json to docs.json. Use these differences to verify the output.
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"] }
]
}
}Component Compatibility
Most Mintlify components have direct Jamdesk equivalents. 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
jamdesk migrate renames CardGroup to Columns in every MDX file. The cols prop carries over unchanged. Check any files you edited after running the migration.
Rename <ResponseField> to <ParamField>. Props stay the same.
{/* Before */}
<ResponseField name="id" type="string" required>
The unique identifier
</ResponseField>
{/* After */}
<ParamField name="id" type="string" required>
The unique identifier
</ParamField>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 fixes this:
- Moves MDX files that are imported as snippets but live outside
/snippets/into/snippets/. It keeps their relative path, so locale-prefixed snippets likede/foo.mdxdon'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>.tsxand replaces the inline export with an import from/snippets/.
Swap Mintlify's <Snippet file="my-snippet.mdx" /> JSX element for an MDX import. The CLI doesn't rewrite it:
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />
{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'
<MySnippet />The relocator aborts without touching anything if your project has no resolved navigation or the planned moves exceed max(5, 25%) of all MDX files. It prints the reason. Fix it and re-run.
Mintlify's topbarLinks and topbarCtaButton map to navbar.links in docs.json. The name field becomes label. The url field becomes href.