从 ReadMe 迁移

使用 Mintlify 抓取工具迁移公开的 ReadMe 项目，或者当你需要迁移私有内容、OpenAPI 规范或多个版本时，从 ReadMe 导出项目文件。

要完成完整迁移，请从原生导出开始，并使用对公开站点的抓取作为对比。这两份清单有助于发现你未发布的页面以及那些没有文件表示的内容。

在 ReadMe 的分支菜单中，将文档文件导出为 ZIP。ReadMe 会通过邮件发送完成的导出。导出的项目结构可以包含 guides、recipes、自定义页面、自定义 blocks、API Reference 内容和 OpenAPI 文件，但不包含图片文件本身。

如果你的项目使用了 ReadMe 的 GitHub 集成，你可以将项目导出到仓库中。ReadMe 文档说明该仓库包含与分支导出相同的内容，并可以包含所有文档版本。

保持导出的内容不变，作为迁移快照。在副本或独立的 Git 分支中进行转换工作。

mkdir mintlify-migration
cd mintlify-migration
npx @mintlify/scraping@latest section https://your-project.readme.io

如果你的站点在特定路径或版本下包含文档，请使用过滤器限制初始迁移：

npx @mintlify/scraping@latest section https://your-project.readme.io --filter=/docs

抓取工具会转换可到达的页面、图片、导航和常见的渲染组件。它无法访问你的私有或未发布内容，也不能替代对原始 OpenAPI 规范的单独导出。

ReadMe 的文件结构通常按类型区分内容。

docs/             按分类组织的 guides
reference/        API 参考页面和 OpenAPI 文件
recipes/          分步的 recipes
custom_pages/     Markdown 或 HTML 自定义页面
custom_blocks/    可复用的自定义 blocks
_order.yaml       文件夹或分类内的顺序

包含子页面的文件夹可以有一个 index.md 作为父页面，并有一个 _order.yaml 定义其子项的顺序。将该结构转换为 docs.json 中嵌套的 group 和 pages 条目。当父级 index.md 包含有价值的概览内容时，将其用作分组的 root。

有关如何构建导航元素的更多信息，请参见 导航。

保留 title、SEO 元数据、描述和有用的关键词。转换 ReadMe 特有的字段。

ReadMe 支持一种自定义的 Markdown 方言和基于 JSON 的 magic blocks。抓取工具会转换常见的渲染组件，但文件导出可能保留平台语法。请检查以下模式，识别必须转换的内容。

• Callouts、tabs、accordions、cards 和 code groups
• Reusable Content 和 Custom Blocks
• 变量和词汇表术语
• 交互式 recipes
• 自定义 HTML 页面
• 嵌入的 API explorer 和个性化内容

将可复用素材转换为 Mintlify snippet。你的导出可能会将可复用 block 展开到每个页面中，请比较副本，仅合并完全相同的内容。

优先使用原始的 OpenAPI 文件，而不是渲染后或导出的端点页面。

1. 在 reference/ 目录以及你曾经与 rdme 或 ReadMe API 同步一起使用的源仓库中，查找每个 JSON 或 YAML OpenAPI 文件。
2. 识别编辑者在规范之外的 ReadMe 中添加的 Markdown。ReadMe 通过 operationId 将这类内容与操作关联起来。
3. 将规范添加到你的 Mintlify 仓库中，并配置 OpenAPI 生成的页面。
4. 将有价值的补充 Markdown 移入相关的操作描述、schema 描述或相邻的指南中。
5. 将认证、服务器 URL、代码示例、示例和端点顺序与原始参考进行比较。

ReadMe 也可以摄取 Swagger 2.0 和 Postman Collection。在配置 Mintlify 之前，请获取转换后或原始的 OpenAPI 源，而不要复制渲染后的参考。

ReadMe 的版本和分支适用于 Guides、Recipes 和 API Reference 内容，而你的一些项目内容会在多个版本之间共享。分别对每个版本建立清单，并将维护的版本映射到 Mintlify 的 版本导航。

检查以下模式。

• 不同的默认版本和 URL 行为
• 隐藏、beta 和已弃用版本
• 特定版本的 Reusable Content
• 只在某一个版本中存在的页面
• 因版本而异的 API 规范
• 共享的 Custom Pages 或更新日志内容

你的 ReadMe ZIP 导出不包含托管的图片。导出的 Markdown 会通过其原始托管 URL（通常位于 files.readme.io）引用这些图片。请在上线之前下载这些文件，并将它们提交到你的 Mintlify 仓库中。

要从导出中下载所有被引用的资源：

1. 在解压后的导出根目录中，从 Markdown 中提取资源 URL：

   grep -rhoE 'https://files\.readme\.io/[^)"\s]+' . | sort -u > asset-urls.txt

2. 将每个文件下载到 Mintlify 仓库的 images/ 目录中：

   mkdir -p images && cd images && wget -i ../asset-urls.txt

3. 更新 Markdown 中的引用，指向新的本地路径（例如，将 https://files.readme.io/abc123-diagram.png 替换为 /images/abc123-diagram.png）。

对于未在导出中被引用的图片或文件（例如，仅附加到 Custom Pages 或从 JSON magic blocks 引用的资源），请使用 ReadMe API 枚举并下载它们。

不要在最终站点上依赖远程 ReadMe 资源 URL。复制你拥有的文件，更新其引用，并验证 alt 文本和可下载文件的链接。

你的 ReadMe URL 可能包含项目版本和内容类型，例如 /docs/、/reference/ 或 /page/。导出 sitemap 或抓取已发布的站点，以获取实际路径。

为每个变更的路径添加 redirects。特别注意：

• 省略了版本段的默认版本 URL
• 位于 /page 下的 Custom Pages
• 具有相同 slug 的 guides 和 reference 页面
• 从 OpenAPI 标签和摘要派生的端点路径
• 仍在接收流量的已弃用或隐藏页面

将 ZIP 导出、API 清单和已发布的 sitemap 与迁移后的文件进行比较，然后预览每个维护的版本。

在你转换后的文件中搜索遗留的 ReadMe 语法：magic blocks、变量、词汇表引用和 Custom Block 指令。

启动你的新站点

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

• 导出数据
• 文档结构
• 版本管理
• OpenAPI 支持
• Reusable Content