迁移指南
从其他文档平台迁移？Jamdesk 可自动完成迁移，也支持手动迁移，让你完全掌控过程。
Mintlify 项目支持一条命令完成迁移：jamdesk migrate 会读取 mint.json、写入 docs.json，并直接重写 MDX 文件。要从 GitBook、Docusaurus、ReadMe、Confluence 或其他平台迁移？“Other Platforms”选项卡会介绍手动迁移步骤。如果你能将内容导出为 Markdown，整个过程会很简短。
如果可以，请先导出为 Markdown。 Jamdesk 基于 MDX 构建，因此已有的 Markdown 文件只需重命名为 .mdx 并添加几行 frontmatter 即可使用。
选择迁移方式
CLI 会为你完成大部分工作。
自动迁移
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 导入。该元素不会被自动重写：
{/* 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。