docusaurus 不解析纯 html 文件，需将 html 重写为 mdx：静态内容转 markdown，内联样式改用注释或 css 类，js 行为替换为官方插件或组件，链接改为相对路径 .md，资源移至 static/ 并更新引用路径，导航与多语言需配置驱动。
HTML 文件直接扔进 docs/ 目录会失效
Docosaurus 默认不解析纯 .html 文件，即使你把它放进 docs/ 目录，访问时会 404 或直接下载——它只认 .md、.mdx 后缀的文档文件。
真正能被识别和渲染的，是经过 Docusaurus 构建流程处理的 Markdown 或 MDX。所以不是“转格式”，而是“重写语义”：把 HTML 的结构、样式、交互意图，映射成 MDX 支持的语法 + React 组件调用。
- 静态内容（如段落、标题、列表）→ 用标准 Markdown 重写即可
- 内联样式（如
<span style="color:red"></span>）→ 改用{/* ... */}注释包裹，或抽成 CSS 类 +<div classname="xxx"> <li>自定义 JS 行为（如折叠面板、代码高亮初始化）→ 必须替换成 Docusaurus 官方插件（如 <code>@docusaurus/theme-live-codeblock）或封装成 MDX 组件 - 相对路径链接（如
<a href="guide.html"></a>）→ 全部改成[指南](./guide.md)，否则构建后跳转失败 - SEO 失效：Docusaurus 的静态生成器无法提取这类内联 HTML 中的文本做索引
- 锚点跳转失效：
<h2 id="section1"></h2>这类手动写的 ID 不会被自动注册到导航栏和右侧 TOC - 主题样式丢失：比如
<pre class="brush:php;toolbar:false;"><code></code> 块不会触发 <code>prism-react-renderer</code> 高亮，也不会响应暗色模式切换</pre> - 安全风险：如果 HTML 来源不可控（比如 CMS 导出），可能执行任意脚本
- 原 HTML 中的
<img src="images/logo.png">→ 改成<img src="/img/logo.png">，并把文件移到static/img/logo.png - 自定义 CSS（如
<link rel="stylesheet" href="css/custom.css">）→ 移到static/css/custom.css，然后在docusaurus.config.js的stylesheets数组里声明 - 第三方 JS（如统计脚本）→ 不要再写
<script src="..."></script>，改用headTags配置项注入，确保在 SSR 阶段也生效 - 注意：Docusaurus 会 hash 所有
static/下的文件名，所以千万别在 HTML 里硬编码带 hash 的路径 - 侧边栏菜单必须在
sidebars.js里显式声明，格式是嵌套对象数组，每个条目对应一个.md文件路径 - 首页 banner（如大标题+按钮）不是靠写 HTML 实现的，而是修改
src/pages/index.mdx，用<homepagefeatures></homepagefeatures>或自定义 React 组件 - 多语言支持（i18n）需提前开启，HTML 中的
<lang></lang>属性不会被识别，翻译必须拆成独立的zh-cn/子目录 + 同名文件 - 搜索功能依赖 Algolia 或本地搜索插件，原 HTML 的
<input type="search">不会自动接入
dangerouslySetInnerHTML 不是万能解药
有人试过在 MDX 里用 {dangerouslySetInnerHTML: {__html: '<p>xxx</p>'}} 强行塞 HTML 字符串，短期能显示，但立刻踩中三个坑：
真要保留部分 HTML 片段，优先用 MDX 的原生能力：<details><summary></summary></details> 写成 <details><summary>...</summary>...</details>；表格用 Markdown 表格语法；复杂布局改用 <grid></grid> 或 <card></card> 等 Docusaurus 内置组件。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
图片、CSS、JS 资源路径全得重定向
Docusaurus 对静态资源有严格归档规则：所有非文档文件必须放在 static/ 目录下，且引用路径以 / 开头（即站点根路径），不能用相对路径。
导航栏、侧边栏、首页 banner 需手动重建
Docusaurus 的导航结构完全由配置驱动，和 HTML 文件物理位置无关。原来 HTML 里写的 <nav></nav> 或顶部面包屑，不会自动变成左侧菜单。
最麻烦的其实是「语义对齐」：比如原 HTML 里一个 <h3>兼容性说明</h3> 在 Docusaurus 里可能要拆成独立的 compatibility.md 页面 + 侧边栏分组 + 版本标签控制可见性——这已经不是迁移，是按 Docusaurus 的信息架构重设计。
