--- title: 迁移指南 description: 从其他文档平台迁移？Jamdesk 可自动完成迁移，也支持手动迁移，让你完全掌控过程。 --- > **For AI agents:** the complete documentation index is at [llms.txt](https://jamdesk.com/docs/llms.txt). Append `.md` to any page URL for its markdown version. See the clean markdown version of this page at https://jamdesk.com/docs/setup/migration.md Mintlify 项目支持一条命令完成迁移：`jamdesk migrate` 会读取 `mint.json`、写入 `docs.json`，并直接重写 MDX 文件。要从 GitBook、Docusaurus、ReadMe、Confluence 或其他平台迁移？“Other Platforms”选项卡会介绍手动迁移步骤。如果你能将内容导出为 Markdown，整个过程会很简短。 **如果可以，请先导出为 Markdown。** Jamdesk 基于 MDX 构建，因此已有的 Markdown 文件只需重命名为 `.mdx` 并添加几行 frontmatter 即可使用。 ## 选择迁移方式 ### From Mintlify CLI 会为你完成大部分工作。 阅读迁移指南，了解背景信息、示例和迁移技巧。 ### 自动迁移 #### 1. 安装 CLI ```bash npm install -g jamdesk ``` #### 2. 运行迁移 ```bash jamdesk migrate ``` 在项目根目录中运行时，该命令会一次性完成以下操作： - 读取 `mint.json` 并写入 `docs.json` - 重命名 MDX 文件中的弃用组件（例如将 `CardGroup` → `Columns`） - 将孤立的片段 MDX 文件移动到 `/snippets/`，并将所有相对于父目录的导入（`../foo/bar.mdx`）重写为相对于根目录的导入（`/snippets/foo/bar.mdx`） - 将使用 React hooks 的内联组件提取到 `/snippets/.tsx`，并添加 `'use client'` 指令，然后重写原始 MDX，使其从 `/snippets/` 导入 - 自动修复可能导致构建失败的机械性 MDX 语法问题 该命令具有幂等性：编辑后重新运行即可，它只会处理新增内容。对于无法安全自动处理的内容，命令会输出警告，并列出相关文件、导入项以及需要执行的操作。 #### 3. 检查并调整 检查生成的 `docs.json` 和 MDX 文件。确认导航结构，以及 CLI 输出的所有警告。 ### 配置映射 CLI 会自动将 `mint.json` 转换为 `docs.json`。以下是主要差异，便于你检查输出结果。 **Mintlify（`mint.json`）：** ```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`）：** ```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 等效组件 | 说明 | |---|---|---| | `` | `` | 语法相同 | | CardGroup | `` | 使用 `cols` 属性指定列数 | | `` | `` | 语法相同 | | `` | `` | 语法相同 | | `` / `` | `` / `` | 语法相同 | | `` / `` | `` / `` | 语法相同 | | `` | `` | 语法相同 | | ``、``、`` | ``、``、`` | 语法相同 | | `` | `` | 名称不同 | | `` | 从 `/snippets/` 导入 | 使用方式不同 | ### 常见问题 #### CardGroup 会变为 Columns `jamdesk migrate` 会在所有 MDX 文件中将 `CardGroup` 重命名为 `Columns`。`cols` 属性会保持不变。运行迁移后，请检查编辑过的文件。 #### ResponseField 会变为 ParamField 将 `` 重命名为 ``。属性保持不变。 ```mdx {/* Before */} The unique identifier {/* After */} The unique identifier ``` #### 片段会自动重新定位并重写导入 Jamdesk 只解析相对于根目录的 `/snippets/*` 导入。Mintlify 项目通常会将片段 MDX 文件放在目录树中的任意位置，并使用相对于父目录的路径导入（`import X from '../shared/x.mdx'`）。 `jamdesk migrate` 会在一次运行中完成以下三项操作： - 检测作为片段导入但位于 `/snippets/` 之外的 MDX 文件，并将其移动到 `/snippets/` 下，同时保留相对路径（因此带有语言区域前缀的片段，如 `de/foo.mdx`，不会发生冲突）。 - 将所有 MDX 文件中的相对于父目录的片段导入重写为新的相对于根目录的路径。 - 将使用 React hooks 的内联组件提取到 `/snippets/.tsx` 中的 `'use client'` 文件，并将内联导出替换为从 `/snippets/` 导入。 如果你使用了 Mintlify 的 `` JSX 元素，请将其替换为 MDX 导入。该元素不会被自动重写： ```mdx {/* Before (Mintlify) */} {/* After (Jamdesk) */} import MySnippet from '/snippets/my-snippet.mdx' ``` 重定位器采取保守策略。如果项目没有已解析的导航，或者计划移动的文件超过所有 MDX 文件的 `max(5, 25%)`，它会在不修改任何内容的情况下中止，并说明原因。修复中止原因后重新运行。 #### topbarLinks 会映射到 navbar.links Mintlify 的 `topbarLinks` 和 `topbarCtaButton` 都会映射到 `docs.json` 中的 `navbar.links`。`name` 字段会变为 `label`，`url` 会变为 `href`。 ### From Other Platforms 适用于 GitBook、ReadMe、Docusaurus、Confluence、Notion 或其他文档工具。 如果使用的平台提供 HTML 导出（例如 Confluence、Notion 以及许多其他平台），可以将内容粘贴到免费的 HTML 转 MDX 转换器中，获得可直接放入项目的整洁 MDX。 需要迁移帮助？[联系我们](mailto:contact@jamdesk.com)，我们会协助你完成设置。 ### 从 GitBook 迁移 GitBook 使用 Markdown 存储内容，并通过 `SUMMARY.md` 文件定义导航。 #### 1. 导出内容 将 GitBook 空间导出为 Markdown。如果使用 GitBook 的 Git 同步功能，内容已经作为 `.md` 文件存储在 Git 仓库中。 #### 2. 将文件转换为 MDX 将 `.md` 文件重命名为 `.mdx`，并为每个文件添加 frontmatter： ```mdx --- title: Your Page Title description: A short description of the page --- Your existing Markdown content here. ``` #### 3. 从 SUMMARY.md 映射导航 GitBook 使用 `SUMMARY.md` 定义侧边栏。将其转换为 `docs.json` 导航组。 **GitBook（`SUMMARY.md`）：** ```markdown # Summary ## Getting Started * [Introduction](introduction.md) * [Quick Start](quickstart.md) ## API Reference * [Authentication](api/auth.md) ``` **Jamdesk（`docs.json`）：** ```json { "navigation": { "groups": [ { "group": "Getting Started", "pages": ["introduction", "quickstart"] }, { "group": "API Reference", "pages": ["api/auth"] } ] } } ``` #### 4. 移动图片 将所有图片移动到 `/images` 目录，并更新 MDX 文件中的引用，使用绝对路径（例如 `/images/screenshot.png`）。 #### 5. 在本地测试 ```bash jamdesk dev ``` ### 从 Docusaurus 迁移 Docusaurus 项目已经使用 MDX，因此大多数内容可以直接迁移。 #### 1. 复制 MDX 文件 将 Docusaurus 的 `docs/` 目录内容复制到 Jamdesk 项目根目录。保留现有目录结构。 #### 2. 清理 frontmatter 删除 Docusaurus 专用的 frontmatter 字段。保留 `title` 和 `description`，删除其余字段。 ```yaml --- # Remove these Docusaurus fields sidebar_position: 3 sidebar_label: "Custom Label" slug: /custom-url pagination_next: null # Keep these title: Your Page Title description: A short description --- ``` #### 3. 将 sidebars.js 映射到 docs.json 将 `sidebars.js` 的分类结构转换为 `docs.json` 导航组。 **Docusaurus（`sidebars.js`）：** ```javascript module.exports = { docs: [ { type: 'category', label: 'Getting Started', items: ['intro', 'installation'], }, ], }; ``` **Jamdesk（`docs.json`）：** ```json { "navigation": { "groups": [ { "group": "Getting Started", "pages": ["intro", "installation"] } ] } } ``` #### 4. 替换 Docusaurus 组件 将 Docusaurus 专用组件替换为 Jamdesk 等效组件。 | Docusaurus | Jamdesk | 示例 | |---|---|---| | `:::note` / `:::tip` / `:::warning` | `` / `` / `` | 查看[提示组件](https://jamdesk.com/docs/cn/components/overview) | | `import Tabs from '@theme/Tabs'` | ``（全局可用） | 无需导入 | | `import TabItem from '@theme/TabItem'` | ``（全局可用） | 使用 `title` 替代 `label` | #### 5. 在本地测试 ```bash jamdesk dev ``` ### 从其他工具迁移 对于 Confluence、Notion、ReadMe 或其他平台，流程都相同：先将内容导出为 Markdown，然后设置 Jamdesk 项目结构。 #### 1. 导出为 Markdown 大多数平台都提供 Markdown 或 HTML 导出选项。如果可用，请使用 Markdown。对于 HTML，可以使用 [Pandoc](https://pandoc.org/) 等工具将其转换为 Markdown。 ```bash # Convert HTML to Markdown with Pandoc pandoc input.html -f html -t markdown -o output.md ``` #### 2. 创建 docs.json 从最小配置开始，并在添加页面时逐步完善导航。 #### 3. 将文件转换为 MDX 将 `.md` 文件重命名为 `.mdx`，并为每个文件添加 frontmatter（`title`、`description`）。 #### 4. 移动资源 将图片和其他资源移动到 `/images` 目录。更新文件引用，使用绝对路径。 #### 5. 在本地测试 ```bash jamdesk dev ``` ## 迁移后检查清单 所有页面均可正常渲染且无错误 导航结构与原网站一致 内部链接均可正常使用 图片和资源均可正常显示 代码块使用正确的语法高亮 搜索已为内容建立索引 ## 接下来做什么？ 了解如何组织文档 配置网站设置