Migration Guide
Moving from another documentation platform? Jamdesk can help automate the transition, or you can migrate manually for full control.
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.
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.
Choose Your Path
The CLI does the bulk of the work for you.
Automated Migration
npm install -g jamdeskjamdesk migrateFrom the project root, this runs in one pass:
- 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, 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.
Check the generated docs.json and MDX files. Verify navigation structure and any warnings printed by the CLI.
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):
{
"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 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
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.
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 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 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/.
If you used Mintlify's <Snippet file="my-snippet.mdx" /> JSX element, swap it for an MDX import — that one isn't auto-rewritten:
{/* 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.
Mintlify's topbarLinks and topbarCtaButton both map to navbar.links in docs.json. The name field becomes label, and url becomes href.