本文介绍如何绕过 iframe，直接将 react 组件集成到 material for mkdocs 构建的静态文档站点中，通过 python-markdown 的 html 支持与 mkdocs 资源配置实现原生渲染。
本文介绍如何绕过 iframe，直接将 react 组件集成到 material for mkdocs 构建的静态文档站点中，通过 python-markdown 的 html 支持与 mkdocs 资源配置实现原生渲染。
在 Material for MkDocs 中嵌入 React 组件，核心在于打破“Markdown 仅限文本”的限制，利用其底层依赖的 Python-Markdown 解析器对混合 HTML 的原生支持，并配合 MkDocs 的静态资源注入能力，让 React 运行时环境真正落地到 Markdown 页面中。
✅ 基础前提：启用 HTML 与内联 Markdown 支持
Material for MkDocs 默认允许在 .md 文件中使用原始 HTML（如 <div>、<script>），但若需在 HTML 标签内继续书写 Markdown（例如在自定义容器中混排文字与列表），需在 mkdocs.yml 中启用 markdown_in_html 扩展：
markdown_extensions: - markdown_in_html
同时，在包含 Markdown 内容的 HTML 元素上添加 markdown="1" 属性，例如：
<div id="react-root" markdown="1"> 这里可写 **Markdown**，也会被正确解析。 </div>
✅ 集成 React：构建 + 注入 + 挂载
React 组件无法直接写在 Markdown 里，需先构建为独立 JS 资源（推荐使用 Vite 或 CRA 的 build 输出），再通过 MkDocs 注入页面：
-
构建组件为轻量 UMD 包（以 Vite 为例）：
在 vite.config.ts 中配置：export default defineConfig({ build: { lib: { entry: 'src/MyWidget.tsx', name: 'MyWidget', fileName: 'my-widget' }, rollupOptions: { external: ['react', 'react-dom'], output: { globals: { react: 'React', 'react-dom': 'ReactDOM' } } } } })构建后生成 dist/my-widget.umd.js，其中导出一个挂载函数（如 MyWidget.render(container)）。
-
配置 MkDocs 加载资源：
在 mkdocs.yml 中声明外部依赖与组件脚本：extra_javascript: - https://unpkg.com/react@18/umd/react.production.min.js - https://unpkg.com/react-dom@18/umd/react-dom.production.min.js - https://unpkg.com/@babel/standalone/babel.min.js # 如需 JSX 实时转译（仅开发） - assets/js/my-widget.umd.js # 你构建的组件包（需复制到 docs/assets/js/） extra_css: - assets/css/my-widget.css # 可选：组件样式
-
在 Markdown 中声明容器并初始化：
## 数据可视化组件 <div id="my-react-widget"></div> <script> // 确保 React 已加载且 DOM 就绪 document.addEventListener('DOMContentLoaded', () => { if (typeof MyWidget !== 'undefined') { MyWidget.render(document.getElementById('my-react-widget')); } }); </script>
⚠️ 注意事项与最佳实践
- 避免全局污染：组件包应使用 IIFE 或 ES 模块封装，不直接向 window 挂载过多变量；推荐导出命名空间对象（如 MyWidget）。
- 样式隔离：为组件容器添加唯一 class（如 class="react-widget"），并在 CSS 中使用 BEM 或 CSS-in-JS 方案防止样式穿透。
- SEO 与 SSR 考量：纯客户端渲染的 React 组件对搜索引擎不可见；如需 SEO，建议改用 MkDocs 插件服务端渲染 或预渲染快照。
- 性能优化：生产环境禁用 Babel Standalone，改用构建时预编译 JSX；大型组件考虑代码分割（import() 动态导入）。
通过以上步骤，你将彻底摆脱 iframe 的滚动冲突、跨域限制与样式隔离难题，让 React 组件成为文档页面的一等公民——兼具交互性与一致性。
