Migration Guide
Moving from another documentation platform? Jamdesk can help automate the transition, or you can migrate manually for full control.
Switching from Mintlify, GitBook, Docusaurus, ReadMe, or another platform? The Mintlify tab covers automated CLI migration. Everything else is a manual process, but it's straightforward if your content is already Markdown.
Markdown yields the best results. If your current platform supports Markdown export, use it. Jamdesk is built on MDX, so Markdown content migrates cleanly.
Choose Your Path
The Jamdesk CLI can automatically convert Mintlify projects.
Automated Migration
npm install -g jamdeskjamdesk migrateThis reads your mint.json, converts it to docs.json, and rewrites component syntax where needed.
Check the generated docs.json and MDX files. The CLI handles most conversions, but you should verify component usage and navigation structure.
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
Rename CardGroup to <Columns>. The cols prop works the same way. The jamdesk migrate CLI handles this, but check any files you've edited manually.
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>Mintlify uses a <Snippet> component. In Jamdesk, use standard MDX imports from a /snippets/ directory.
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />
{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'
<MySnippet />Mintlify's topbarLinks and topbarCtaButton both map to navbar.links in docs.json. The name field becomes label, and url becomes href.