从 Docusaurus 迁移

使用 Mintlify 抓取工具迁移公开的 Docusaurus 2 或 3 站点。如果你需要对版本、本地化内容或自定义 React 组件进行更精确的控制，请从源仓库迁移。

对于复杂站点，可以同时使用两种方式。抓取公开站点以创建初始的 docs.json 并转换组件，然后将结果与源仓库进行比较以发现遗漏的内容。

mkdir mintlify-migration
cd mintlify-migration
npx @mintlify/scraping@latest section https://docs.example.com

如果你的 Docusaurus 文档使用了路由基础路径，请使用过滤器抓取该路径：

npx @mintlify/scraping@latest section https://example.com --filter=/docs

抓取工具会检测 Docusaurus、展开其侧边栏、下载可到达的图片、将常见的渲染组件转换为 Mintlify 组件，并根据已发布的导航创建 docs.json。

抓取工具运行完成后，将生成的 Mintlify 导航与你的 sidebars.js、sidebars.ts 或其他 Docusaurus 导航结构进行比较。检查折叠的分类、外部链接、生成的分类索引页，以及从已发布侧边栏中排除的页面。

将以下源内容复制到独立的迁移分支或工作目录中。

• 你配置的文档内容目录，在 Docusaurus 中默认是 docs/
• sidebars.js、sidebars.ts 或其他侧边栏配置文件
• docusaurus.config.js 或 docusaurus.config.ts
• _category_.json、_category_.yml 或 _category_.yaml 文件
• static/ 目录以及与文档页面一同存放的资源
• versioned_docs/、versioned_sidebars/ 和 versions.json
• 位于 i18n/<locale>/docusaurus-plugin-content-docs/<versionName>/ 下的本地化文档，例如 current/
• 被 MDX 页面导入的 React 组件

将 Markdown 和 MDX 页面复制到你的 Mintlify 项目中。每个页面至少需要包含 title 的 frontmatter。

---
title: "开始使用"
description: "安装 SDK 并发起第一次请求。"
---

Docusaurus 的侧边栏是可执行的 JavaScript 或 TypeScript，而 Mintlify 的导航是 docs.json 中的数据。如果侧边栏使用了函数或自定义生成器，请转换已解析后的侧边栏，而不仅是其源文本。

Docusaurus 使用文件层级来自动生成侧边栏。Mintlify 允许你独立于文件位置来组织导航，因此你不需要仅为了匹配侧边栏而重命名页面。

标准的 Markdown 通常无需修改即可使用。请检查 Docusaurus 特有的语法和导入。

自定义 React 组件不会从你的源仓库自动迁移。判断每个组件属于内容、表现层还是应用行为。

• 使用 Mintlify 组件 替换内容型模式。
• 将重复内容转换为 可复用的 snippet。
• 当你需要内置组件都无法提供的交互时，添加一个 React 组件。
• 将完整的应用页面移出文档站点，或作为 自定义页面布局 重建。

Docusaurus 会结合文档插件的 routeBasePath、页面 frontmatter 的 slug、版本和语言环境来生成 URL。请根据已发布的 sitemap 建立清单，而不是仅从文件名推断每个 URL。

当你重命名或重新组织页面时，将其旧的已发布路径添加到 redirects。分别使用和不使用旧的路由基础路径来测试链接，例如 /docs/getting-started 和 /getting-started。

检查 Docusaurus 显式指定的标题 ID，例如：

## Configure the client {/* #configure-client */}

当你必须保留入站锚点链接时，将它们转换为 Mintlify 的自定义标题 ID 语法：

## Configure the client [#configure-client]

Docusaurus 支持位于 static/ 中的全局资源以及与带版本页面一同存放的资源。将这两类资源都复制到 Mintlify 仓库。

• Docusaurus 中位于 static/img/logo.png 的文件通常被发布为 /img/logo.png。请保留这个公共路径，否则需要更新每一处引用。
• 在移除 Docusaurus 导入之前，先解析 @site/static/... 导入。
• 将带版本的相邻资源保留在对应版本中，或将其移至版本特定的资源目录。
• 检查 CSS 背景图片和 React 组件的导入，仅基于 Markdown 的清单可能会遗漏它们。
• 除非你在迁移后打算继续保留旧的托管环境，否则不要将必需的生产资源留在旧的部署上。

Docusaurus 将冻结的版本存放在 versioned_docs/version-<name> 下，并将其导航存放在 versioned_sidebars/ 下。将每个维护的版本映射到 Mintlify 的 版本。决定 current、最新发布的版本，还是其他某个版本应作为默认版本。

将 Docusaurus 的语言环境目录映射到 Mintlify 的 语言导航。当旧站点使用像 /fr/docs/... 这样的路径时，在重定向中保留语言环境前缀。

如果你的源仓库包含未发布或受限的页面，请配置 认证 和页面可见性，然后分别以未登录用户和各分组成员的身份测试你的站点。

定位被插件、自定义页面或构建脚本引用的 OpenAPI 或 AsyncAPI 文件。将原始规范添加到 Mintlify 仓库，并配置 OpenAPI 生成的页面。当源规范可用时，不要迁移已渲染的端点 HTML。

将迁移后的页面与侧边栏条目和已发布的 sitemap 进行比较，然后预览每个维护的版本和语言。

在你转换后的文件中搜索遗留的 Docusaurus 语法，这些语法会被渲染为字面文本或导致构建失败：@theme、@site、:::、DocCardList、useDocusaurusContext 和自定义插件导入。

启动你的新站点

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

• 文档插件配置
• 侧边栏
• 版本管理
• 国际化
• 静态资源
• 标题 ID