Migration Guide
Moving from another documentation platform? Jamdesk can help automate the transition, or you can migrate manually for full control.
If you're switching from Mintlify, GitBook, Docusaurus, or another platform, this guide covers automated migration with the CLI and manual setup for full control over the process.
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, but here's what changes 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 |
<Columns> | <Columns> | Use cols prop for column count |
<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
Mintlify's <Columns cols={2}> becomes <Columns cols={2}> in Jamdesk. The jamdesk migrate CLI handles this, but check any files you've edited manually.
{/* Before (Mintlify) */}
<Columns cols={2}>
<Card title="First" />
<Card title="Second" />
</Columns>
{/* After (Jamdesk) */}
<Columns cols={2}>
<Card title="First" />
<Card title="Second" />
</Columns>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.
Sample Jamdesk Configuration
Start with a minimal docs.json and expand as you migrate more pages:
{
"$schema": "https://jamdesk.com/docs.json",
"name": "My Product Docs",
"theme": "jam",
"navigation": {
"groups": [
{
"group": "Getting Started",
"pages": ["introduction", "quickstart"]
}
]
}
}