如何将HTML文件及React组件集成到Markdown网页（基于Material for MkDocs）

步骤1：打包React组件为浏览器可直接加载的格式 #

首先需要把你的React组件打包成UMD或IIFE格式，确保能在浏览器环境中直接运行，无需额外构建工具。以Vite为例，修改vite.config.js：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: 'src/YourComponent.jsx', // 你的组件入口文件路径
      name: 'YourReactComponent', // 全局暴露的组件名称
      formats: ['umd'],
      fileName: (format) => `your-component.${format}.js`
    }
  }
})

执行npm run build后，dist目录会生成可直接使用的UMD脚本文件。

步骤2：将构建产物放入静态资源目录 #

把打包好的your-component.umd.js（以及组件对应的CSS文件，如果有独立样式）复制到Material for MkDocs的静态资源目录，比如docs/static/js/和docs/static/css/。

步骤3：在Markdown文件中嵌入组件 #

在需要展示组件的Markdown文件中，按以下结构编写：

1. 添加组件容器：

<div id="react-component-container" style="width: 100%; min-height: 400px; overflow-y: auto;"></div>

这里的样式可按需调整，overflow-y: auto用于处理组件内部滚动，避免和页面全局滚动冲突。

2. 引入依赖脚本和组件脚本：

<!-- 若组件打包时未内置React/ReactDOM，需先引入 -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<!-- 引入你的组件脚本 -->
<script src="../static/js/your-component.umd.js"></script>
<!-- 若有独立样式文件，引入CSS -->
<link rel="stylesheet" href="../static/css/your-component.css">

3. 添加渲染脚本：

<script>
  const container = document.getElementById('react-component-container');
  const root = ReactDOM.createRoot(container);
  // 若需传递props，可在createElement第二个参数传入对象
  root.render(React.createElement(YourReactComponent));
</script>

步骤4：全局优化（可选） #

如果多个页面都需要嵌入该组件，可把公共脚本配置到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
  - static/js/your-component.umd.js
extra_css:
  - static/css/your-component.css

之后在Markdown文件中只需添加容器和渲染脚本即可。

注意事项 #

• 确保组件打包时不依赖Node.js专属API，避免浏览器运行报错。
• 调整组件内部滚动样式，比如给组件内的滚动容器设置max-height，配合外层容器的overflow-y: auto，保证滚动行为符合预期。
• 测试不同屏幕尺寸下的显示效果，确保组件适配Material for MkDocs的页面布局。

内容的提问来源于stack exchange，提问作者dtsr00