迁移指南
使用 jamdesk migrate 迁移 Mintlify 项目，将 mint.json 转为 docs.json 并就地改写 MDX 文件。
只需运行一条命令即可迁移 Mintlify 项目：jamdesk migrate 会读取 mint.json、写入 docs.json，并就地改写 MDX 文件。对于 GitBook、Docusaurus、ReadMe、Confluence 或其他平台，请按照“其他平台”标签页中的手动步骤操作。
如果可以，请先导出为 Markdown。 Jamdesk 基于 MDX 构建。只需将 Markdown 文件重命名为 .mdx，再添加几行 frontmatter 即可。
选择迁移方式
自动迁移
npm install -g jamdeskjamdesk migrate请在项目根目录运行。此命令会执行以下操作：
- 读取
mint.json并写入docs.json - 重命名 MDX 文件中的弃用组件（例如
CardGroup→Columns） - 将无父级引用的片段 MDX 文件移至
/snippets/，并将所有父级相对导入路径（../foo/bar.mdx）改写为根目录相对路径（/snippets/foo/bar.mdx） - 将使用 React hooks 的内联组件提取到
/snippets/<name>.tsx，添加'use client'指令，并改写原始 MDX 文件，使其从/snippets/导入 - 自动修复会导致构建失败的机械性 MDX 语法问题
此命令具有幂等性。编辑后可重新运行，只处理新增内容。对于无法安全修复的问题，命令会输出警告，列出文件、导入语句和建议采取的操作。
检查生成的 docs.json 和 MDX 文件。确认导航结构，并修复 CLI 输出的所有警告。
配置映射
CLI 会将 mint.json 转换为 docs.json。请根据以下差异检查转换结果。
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"] }
]
}
}组件兼容性
大多数 Mintlify 组件在 Jamdesk 中都有直接对应项。少数组件的名称或语法有所不同。
| Mintlify 组件 | Jamdesk 对应项 | 说明 |
|---|---|---|
<Card> | <Card> | 语法相同 |
| CardGroup | <Columns> | 使用 cols 属性设置列数 |
<Columns> | <Columns> | 语法相同 |
<Accordion> | <Accordion> | 语法相同 |
<Tabs> / <Tab> | <Tabs> / <Tab> | 语法相同 |
<Steps> / <Step> | <Steps> / <Step> | 语法相同 |
<CodeGroup> | <CodeGroup> | 语法相同 |
<Tip>、<Note>、<Warning> | <Tip>、<Note>、<Warning> | 语法相同 |
<ResponseField> | <ParamField> | 名称不同 |
<Snippet> | 从 /snippets/ 导入 | 用法不同 |
常见问题
jamdesk migrate 会在每个 MDX 文件中将 CardGroup 重命名为 Columns。cols 属性会原样保留。请检查迁移后编辑过的文件。
将 <ResponseField> 重命名为 <ParamField>。属性保持不变。
{/* Before */}
<ResponseField name="id" type="string" required>
The unique identifier
</ResponseField>
{/* After */}
<ParamField name="id" type="string" required>
The unique identifier
</ParamField>Jamdesk 只会解析根目录相对的 /snippets/* 导入路径。Mintlify 项目通常会将片段 MDX 文件放在目录树的任意位置，并使用父级相对路径导入（import X from '../shared/x.mdx'）。
jamdesk migrate 会修复此问题：
- 将作为片段导入、但位于
/snippets/之外的 MDX 文件移至/snippets/。文件的相对路径会保留，因此带有区域设置前缀的片段（如de/foo.mdx）不会发生冲突。 - 将每个 MDX 文件中的所有父级相对片段导入路径改写为新的根目录相对路径。
- 将使用 React hooks 的内联组件提取到
/snippets/<name>.tsx下的'use client'文件中，并将内联导出替换为从/snippets/导入。
请将 Mintlify 的 <Snippet file="my-snippet.mdx" /> JSX 元素替换为 MDX 导入。CLI 不会改写此元素：
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />
{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'
<MySnippet />如果项目没有已解析的导航，或计划移动的文件数量超过所有 MDX 文件的 max(5, 25%)，迁移工具会中止操作，不做任何更改，并输出原因。请修复问题后重新运行。
Mintlify 的 topbarLinks 和 topbarCtaButton 会映射到 docs.json 中的 navbar.links。name 字段会转换为 label，url 字段会转换为 href。