mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
e47328c4d8
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
152 lines
5.7 KiB
Plaintext
152 lines
5.7 KiB
Plaintext
---
|
||
title: "从其他平台迁移"
|
||
description: "将文档从任意平台转换为 Mintlify 的页面、导航、组件、API 参考、资源和重定向。"
|
||
keywords: ["手动文档迁移", "Markdown 迁移", "MDX 迁移", "docs.json"]
|
||
---
|
||
|
||
import MigrationLaunchChecklist from "/snippets/zh/migration-launch-checklist.mdx";
|
||
|
||
当你当前的平台不在受支持的平台列表中、站点是私有的，或你需要对最终结构进行完全控制时，请使用手动迁移。
|
||
|
||
<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](/zh/organize/pages)。
|
||
|
||
<div id="design-your-navigation">
|
||
## 设计导航
|
||
</div>
|
||
|
||
你可以忠实地重现现有的导航结构，也可以借助本次迁移改善用户查找内容的方式。
|
||
|
||
使用适当的 [导航结构](/zh/organize/navigation)。下表展示了托管在 Mintlify 上的站点常见的导航模式。
|
||
|
||
| 内容模型 | Mintlify 导航元素 |
|
||
| --- | --- |
|
||
| 单一文档集 | Groups 和 pages |
|
||
| 不同的产品 | Products |
|
||
| 主要内容区域 | Tabs 或 anchors |
|
||
| 受支持的发布版本 | Versions |
|
||
| 翻译后的文档 | Languages |
|
||
| 分组概览 | 带 `root` 页面的 group |
|
||
|
||
除非你打算隐藏该页面，否则将每个页面路径都添加到 `docs.json`。[隐藏页面](/zh/organize/hidden-pages) 仍可通过 URL 访问，但默认情况下会被排除在站点搜索、sitemaps、搜索引擎索引和 AI 上下文之外。
|
||
|
||
<div id="convert-your-content">
|
||
## 转换你的内容
|
||
</div>
|
||
|
||
纯 Markdown 通常几乎不需要转换。用 Mintlify 组件替换平台特定的语法。
|
||
|
||
| 源模式 | Mintlify 功能 |
|
||
| --- | --- |
|
||
| Note、tip、warning 或 danger 块 | [Callout](/zh/components/callouts) |
|
||
| 可折叠区块 | [Accordion](/zh/components/accordions) |
|
||
| 替代说明 | [Tabs](/zh/components/tabs) |
|
||
| 多个代码示例 | [Code group](/zh/components/code-groups) |
|
||
| 链接资源磁贴 | [Cards](/zh/components/cards) |
|
||
| 顺序化流程 | [Steps](/zh/components/steps) |
|
||
| 复用的内容 | [可复用 snippet](/zh/create/reusable-snippets) |
|
||
| 交互式或应用特定的 UI | [React 组件](/zh/customize/react-components) |
|
||
|
||
在你转换后的文件中搜索源平台的指令、导入、模板变量、原始 HTML 和未解析的 include。这些模式通常会被渲染为文本，或在 MDX 构建时失败。
|
||
|
||
<div id="migrate-api-documentation">
|
||
## 迁移 API 文档
|
||
</div>
|
||
|
||
当存在原始的 OpenAPI 或 AsyncAPI 规范或 GraphQL schema 时，找到它。将源文件添加到你的 Mintlify 仓库，并按照相应的设置指南操作。
|
||
|
||
- [OpenAPI 设置](/zh/api-playground/openapi-setup)
|
||
- [AsyncAPI 设置](/zh/api-playground/asyncapi-setup)
|
||
- [GraphQL 设置](/zh/api-playground/graphql-setup)
|
||
|
||
如果你的源平台在规范之外存储了端点描述，请将有用的内容合并到规范中，或放到相邻的指南中。将操作顺序、认证、服务器 URL、示例、schema 和代码示例与旧站点进行比较。
|
||
|
||
你可以使用 Mintlify 抓取工具包生成初始的 OpenAPI 端点页面：
|
||
|
||
```bash
|
||
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 创建到其目标的映射。每当路径名发生变化时，添加一个 [重定向](/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。
|
||
|
||
<MigrationLaunchChecklist />
|