> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 从其他平台迁移

> 将文档从任意平台转换为 Mintlify 的页面、导航、组件、API 参考、资源和重定向。

当你当前的平台不在受支持的平台列表中、站点是私有的，或你需要对最终结构进行完全控制时，请使用手动迁移。

<div id="collect-your-source-content">
  ## 收集源内容
</div>

在转换之前先导出或复制所有内容。

1. 来自源仓库的 Markdown 或 MDX 文件
2. 来自当前平台的原生 Markdown 或 HTML 导出
3. 通过当前平台的 API 获取的内容
4. 来自已发布站点的渲染 HTML
5. 手动复制和转换

保持原始导出不变。在副本中进行转换工作，以便进行比较或重启迁移。

创建一份清单，包含每个页面的源标识符、标题、已发布 URL、目标路径、内容类型、版本、语言和迁移状态。包括那些应保持可用的未发布页面。

<div id="create-your-mintlify-project">
  ## 创建 Mintlify 项目
</div>

一个典型的 Mintlify 项目包含：

* 用于站点设置和导航的 `docs.json` 文件
* 用于非从 API 规范生成的页面的 Markdown 或 MDX 文件
* 你希望从仓库中托管的图片和可下载文件
* 可选的 OpenAPI 或 AsyncAPI 规范或 GraphQL schema，用于生成 API 文档

有关受支持的 frontmatter 和文件行为，请参见 [Pages](/docs/zh/organize/pages)。

<div id="design-your-navigation">
  ## 设计导航
</div>

你可以忠实地重现现有的导航结构，也可以借助本次迁移改善用户查找内容的方式。

使用适当的 [导航结构](/docs/zh/organize/navigation)。下表展示了托管在 Mintlify 上的站点常见的导航模式。

| 内容模型     | Mintlify 导航元素      |
| -------- | ------------------ |
| 单一文档集    | Groups 和 pages     |
| 不同的产品    | Products           |
| 主要内容区域   | Tabs 或 anchors     |
| 受支持的发布版本 | Versions           |
| 翻译后的文档   | Languages          |
| 分组概览     | 带 `root` 页面的 group |

除非你打算隐藏该页面，否则将每个页面路径都添加到 `docs.json`。[隐藏页面](/docs/zh/organize/hidden-pages) 仍可通过 URL 访问，但默认情况下会被排除在站点搜索、sitemaps、搜索引擎索引和 AI 上下文之外。

<div id="convert-your-content">
  ## 转换你的内容
</div>

纯 Markdown 通常几乎不需要转换。用 Mintlify 组件替换平台特定的语法。

| 源模式                         | Mintlify 功能                                 |
| --------------------------- | ------------------------------------------- |
| Note、tip、warning 或 danger 块 | [Callout](/docs/zh/components/callouts)          |
| 可折叠区块                       | [Accordion](/docs/zh/components/accordions)      |
| 替代说明                        | [Tabs](/docs/zh/components/tabs)                 |
| 多个代码示例                      | [Code group](/docs/zh/components/code-groups)    |
| 链接资源磁贴                      | [Cards](/docs/zh/components/cards)               |
| 顺序化流程                       | [Steps](/docs/zh/components/steps)               |
| 复用的内容                       | [可复用 snippet](/docs/zh/create/reusable-snippets) |
| 交互式或应用特定的 UI                | [React 组件](/docs/zh/customize/react-components)  |

在你转换后的文件中搜索源平台的指令、导入、模板变量、原始 HTML 和未解析的 include。这些模式通常会被渲染为文本，或在 MDX 构建时失败。

<div id="migrate-api-documentation">
  ## 迁移 API 文档
</div>

当存在原始的 OpenAPI 或 AsyncAPI 规范或 GraphQL schema 时，找到它。将源文件添加到你的 Mintlify 仓库，并按照相应的设置指南操作。

* [OpenAPI 设置](/docs/zh/api-playground/openapi-setup)
* [AsyncAPI 设置](/docs/zh/api-playground/asyncapi-setup)
* [GraphQL 设置](/docs/zh/api-playground/graphql-setup)

如果你的源平台在规范之外存储了端点描述，请将有用的内容合并到规范中，或放到相邻的指南中。将操作顺序、认证、服务器 URL、示例、schema 和代码示例与旧站点进行比较。

你可以使用 Mintlify 抓取工具包生成初始的 OpenAPI 端点页面：

```bash theme={null}
npx @mintlify/scraping@latest openapi-file ./openapi.yaml -o api-reference
```

<div id="migrate-your-assets">
  ## 迁移你的资源
</div>

将你拥有的图片、视频、字体和可下载文件复制到你的仓库中。在可行的情况下保留现有的公共路径，以减少链接更改。

检查以下模式以识别需要迁移的资源。

* Markdown 图片和链接目标
* HTML `<img>` 和 `<video>` 元素
* CSS 背景图片
* 被导入组件所引用的资源
* 由旧文档提供商托管的文件
* 特定版本和特定语言的资源

除非你在迁移后打算继续保留旧提供商的托管，否则不要将必需的生产资源留在旧提供商的域名上。

<div id="preserve-urls">
  ## 保留 URL
</div>

为每个旧的已发布 URL 创建到其目标的映射。每当路径名发生变化时，添加一个 [重定向](/docs/zh/create/redirects)。

在重定向映射中包含以下模式。

* 迁移过程中被删除或合并的页面
* 版本和语言前缀
* 分类或 space 前缀
* 自定义着陆页
* API 端点页面
* 显式 slug 和旧的别名

<div id="recreate-your-site-features">
  ## 重建站点功能
</div>

内容导出通常不包含平台配置。清点并重建你仍需要的功能。

* 自定义域名和 DNS
* 认证和页面可见性
* 分析和标签管理器
* 搜索行为
* 自定义脚本和样式
* 反馈和支持集成
* 更新日志
* SEO 元数据、canonical URL 和索引规则

<div id="review-your-migration">
  ## 检查你的迁移
</div>

将迁移后的项目与内容清单进行比较，然后确认每个预期的页面、版本和语言都能正确解析。

在你转换后的文件中搜索遗留的源平台语法：指令、导入、模板变量、原始 HTML 和未解析的 include。

## 启动你的新站点

* 在旧站点上执行内容冻结，并跟踪迁移快照之后对其所做的每项更改。
* 在仪表板的 [Git 设置](https://app.mintlify.com/settings/deployment/git-settings) 页面确认生产分支和仓库。
* 记录你现有的 DNS 记录，并在验证 Mintlify 部署已上线之前保持旧站点继续运行。
* 检查导航栏、页脚、favicon、logo、颜色和字体。
* 检查站点和页面的元数据、canonical URL 以及索引偏好设置。参见 [SEO 和搜索设置](/docs/zh/organize/settings-seo)。
* 安装所需的 [分析集成](/docs/zh/integrations/analytics/overview)，并可选择添加一个 [自定义 404 页面](/docs/zh/customize/custom-404-page)。
* 如果你迁移了 API 参考，请将端点页面、导航结构、服务器 URL、认证方案和示例与旧站点进行比较。
* 在 [预览部署](/docs/zh/deploy/preview-deployments) 中预览你确切的启动提交。检查桌面和移动端布局、来自每个导航区段的页面、搜索以及重定向。
* 检查使用自定义组件或脚本的页面在浏览器控制台和网络标签页中是否有任何错误。
* 使用 [自定义域名指南](/docs/zh/customize/custom-domain) 切换你的域名，该指南涵盖了对已提供文档服务的域名的零停机切换。
* 启动后，监控 404 错误、重定向失败和构建失败。


## Related topics

- [页面](/docs/zh/organize/pages.md)
- [迁移概览](/docs/zh/migration/index.md)
- [从 Document360 迁移](/docs/zh/migration/document360.md)