从 Fern 迁移
将 Fern 的 MDX 内容、docs.yml 导航、products、versions、资源、API 参考和组件迁移到 Mintlify。
从 Git 仓库迁移 Fern 站点。Fern 将文档以 Markdown 或 MDX 的形式与 docs.yml、资源和 API 规范一并存储，因此源仓库比已发布的 HTML 更完整、更可靠。
Mintlify 抓取工具目前不支持 Fern。
创建一个迁移分支或文档仓库的副本。
定位所有以下项：
fern/docs.yml，用于定义站点设置和导航- MDX 页面，通常位于
fern/docs/pages/ - 图片、视频、favicon 和 logo 资源，通常位于
fern/docs/assets/ - 可复用的 MDX snippet，通常位于
fern/docs/snippets/ - 位于
fern/docs/changelog/的更新日志条目 fern/styles.css和其他自定义 CSS 或 JavaScriptfern/fern.config.json和固定的 Fern CLI 版本- OpenAPI、AsyncAPI 和 Fern 定义文件
generators.yml以及用于获取或生成 API 规范的脚本- 被
docs.yml引用的产品、版本和 tab 配置文件 - 自定义 MDX 组件
- 在运行
fern check或fern docs dev时所需的任何环境变量、远程规范、生成文件或私有包
Fern 保留了 fern 和 changelog 文件夹名。其他所有文件夹名都可配置，所以在移动文件之前，请对照 docs.yml 确认你的目录名。
Fern 在 docs.yml 中定义导航，或在单独的 products 和 versions 文件中定义。Mintlify 在 docs.json 中定义导航。
| Fern | Mintlify |
|---|---|
带 path 的 page | pages 数组中的页面路径 |
section | 导航分组 |
带 path 的 section | 带 root 页面的分组 |
folder | 显式列出页面的导航分组 |
link | 导航链接、anchor、菜单项或 card |
tabs | docs.json 中的 tabs |
products | docs.json 中的 products |
| 全站范围的版本 | docs.json 中的 versions |
hidden: true | 页面 frontmatter 中的 hidden: true 或隐藏的导航条目 |
Fern 会根据 sections、folders、tabs、versions、products 和 pages 的 slug 构建路由。不要仅根据源文件名推断旧的 URL。导出已发布的 sitemap，并在创建重定向之前解析 slug、skip-slug 和页面级的路径覆盖。
当 Fern 的 folder 使用 index.mdx 作为概览时，将该页面用作 Mintlify 分组的 root。保留有意的导航顺序，而不要依赖 Fern 按字母顺序的文件夹发现。
大多数标准 Markdown 和 MDX 可以直接迁移。每个 Mintlify 页面都需要一个 title。保留描述、关键词和其他有用的 SEO 元数据。
检查 Fern 特有的 frontmatter，例如：
slug和路径覆盖availability徽章- 页面布局和目录设置
- 可见性和索引控制
- API 参考关联
使用 Mintlify 的 frontmatter、导航或内容重现相应行为。对于没有等效呈现方式的可用性状态，添加 callout。
Fern 和 Mintlify 都使用 MDX 组件，但组件名称和属性并不可互换。请在每个页面中搜索 JSX 标签和导入，而不要假设它们的渲染方式不变。
| Fern 内容 | Mintlify 处理方式 |
|---|---|
| Callouts | 转换为 Note、Tip、Info、Warning 或 Danger。 |
Tabs 和 Tab | 将属性和标签转换为 Tabs 和 Tab。 |
| Steps | 转换为 Steps 和 Step。 |
| Accordions | 转换为 AccordionGroup 和 Accordion。 |
| Cards 和按钮 | 映射到 Mintlify cards 和受支持的链接。 |
Versions block | 使用 tabs 或独立的带版本页面，取决于选择应影响单个 block 还是整个站点。 |
If block | 按产品或版本拆分内容，或在必须使用条件渲染时使用受支持的自定义组件。 |
| API schema 和端点 snippet 组件 | 从原始 API 规范生成参考，并将补充说明性文本移入指南或操作描述中。 |
来自 fern/docs/snippets/ 的可复用 MDX snippet | 转换为 Mintlify snippet 并更新每个导入路径。 |
| 自定义 MDX 组件 | 使用 React 组件 重建，或用内置组件替换。 |
转换完成后移除仅用于 Fern 的导入。预览使用嵌套组件的页面，因为即使两个平台使用相同的组件名称，有效的语法和支持的属性也可能不同。
使用你的 API 规范创建新的 API 参考页面。
- 追踪每个
api导航条目到其 OpenAPI、AsyncAPI 或 Fern 定义源。 - 下载构建过程从 URL 或其他仓库获取的规范。
- 保留 overlays、生成的示例、认证配置和自定义端点说明。
- 将源规范添加到 Mintlify 仓库，并配置 API 参考页面。
- 将端点分组、servers、安全方案、示例和 SDK snippet 与 Fern 站点进行比较。
Fern 定义可以包含无法直接在 OpenAPI 文档中表示的信息。检查生成的 OpenAPI 输出，并在停用 Fern 构建之前移动任何缺失的描述或示例。
Fern 可以将导航放在特定产品或特定版本的 YAML 文件中。清点每个被引用的文件，并将每个维护的 product 和 version 映射到对应的 Mintlify 导航结构。
检查：
- 位于 product 导航之外的着陆页
- 具有不同页面树的 products 或 versions
- 由 product、version 或 tab 级别添加的 slug
- 特定版本的 API 规范
- 隐藏、已弃用或预发布的 section
- 链接到其他站点的外部 product
从配置的资源目录复制文件，并在移动页面后更新相对路径。除非你在迁移后打算继续保留旧的托管环境，否则不要将必需的生产资源留在旧部署上。检查 docs.yml 中的 logos、favicons、社交图片、字体、颜色、导航栏链接、公告横幅、重定向、分析、自定义 CSS 和自定义 JavaScript。
在 docs.json 中重建受支持的设置。将 CSS 和 JavaScript 视为需要评估的需求，而不是要盲目复制的文件，因为它们的选择器和运行时假设是平台特定的。
将 docs.yml 中的每个导航条目和发现的文件夹页面与 docs.json 进行比较，然后验证每个 product、version 和 tab。
在你转换后的文件中搜索遗留的 Fern 语法：组件导入、不受支持的 JSX 属性，以及 Versions 或 If block。
启动你的新站点
- 在旧站点上执行内容冻结，并跟踪迁移快照之后对其所做的每项更改。
- 在仪表板的 Git 设置 页面确认生产分支和仓库。
- 记录你现有的 DNS 记录，并在验证 Mintlify 部署已上线之前保持旧站点继续运行。
- 检查导航栏、页脚、favicon、logo、颜色和字体。
- 检查站点和页面的元数据、canonical URL 以及索引偏好设置。参见 SEO 和搜索设置。
- 安装所需的 分析集成，并可选择添加一个 自定义 404 页面。
- 如果你迁移了 API 参考，请将端点页面、导航结构、服务器 URL、认证方案和示例与旧站点进行比较。
- 在 预览部署 中预览你确切的启动提交。检查桌面和移动端布局、来自每个导航区段的页面、搜索以及重定向。
- 检查使用自定义组件或脚本的页面在浏览器控制台和网络标签页中是否有任何错误。
- 使用 自定义域名指南 切换你的域名，该指南涵盖了对已提供文档服务的域名的零停机切换。
- 启动后，监控 404 错误、重定向失败和构建失败。