HTML转Docusaurus：快速迁移教程

本文深入解析了将传统HTML文档迁移到Docusaurus平台的核心挑战与实操路径，强调这并非简单的文件格式转换，而是一场围绕语义重构、架构适配与生态融合的系统性工程：需将HTML内容重写为MDX，剥离内联样式与JS行为并替换为Docusaurus原生组件和插件，严格规范静态资源路径与导航配置，彻底摒弃dangerouslySetInnerHTML等权宜之计，并按其信息架构重新设计侧边栏、多语言支持与搜索功能——真正实现从“能用”到“好用”的专业文档站点升级。

HTML 文件直接扔进 docs/ 目录会失效

Docosaurus 默认不解析纯 .html 文件，即使你把它放进 docs/ 目录，访问时会 404 或直接下载——它只认 .md、.mdx 后缀的文档文件。

真正能被识别和渲染的，是经过 Docusaurus 构建流程处理的 Markdown 或 MDX。所以不是“转格式”，而是“重写语义”：把 HTML 的结构、样式、交互意图，映射成 MDX 支持的语法 + React 组件调用。

• 静态内容（如段落、标题、列表）→ 用标准 Markdown 重写即可
• 内联样式（如 ）→ 改用 {/* ... */} 注释包裹，或抽成 CSS 类 +
• 自定义 JS 行为（如折叠面板、代码高亮初始化）→ 必须替换成 Docusaurus 官方插件（如 @docusaurus/theme-live-codeblock）或封装成 MDX 组件
• 相对路径链接（如 ）→ 全部改成 [指南](./guide.md)，否则构建后跳转失败

dangerouslySetInnerHTML 不是万能解药

有人试过在 MDX 里用 {dangerouslySetInnerHTML: {__html: '

xxx