应提取文档区块（如）而非整页html，用包裹并克隆插入，确保css类带前缀、避免iframe嵌入，并同步cdn与文档版本。
HTML模板里怎么塞进自动生成的组件文档
直接把文档生成结果当静态 HTML 片段塞进模板就行，但得保证结构干净、样式隔离、不污染全局。Vant Weapp 那套文档生成流程输出的是纯 HTML + CSS（不含 JS 运行时），正好能和手写 HTML 模板无缝拼接。
常见错误是把 index.html 里整个 内容复制进模板，结果 class 名冲突、style 标签重复、h1 层级错乱。真正该拿的只有文档区块本身——比如 Vant 的 <div class="demo-section"> 或 <code><section class="api-docs"></section> 这类带明确语义和作用域的容器。
- 用
<template id="doc-card"></template>包裹生成的文档 HTML，避免被浏览器提前解析或渲染 - JS 加载时用
document.getElementById('doc-card').content.cloneNode(true)插入，不破坏原有 DOM 结构 - 确保生成文档的 CSS 类名带前缀（如
vant-button--demo），否则会和模板里已有的btn类打架
为什么不能直接用
<iframe></iframe> 看似省事，实际会卡死调试、阻断样式继承、让锚点跳转失效，还可能触发跨域限制（尤其本地开发时 file:// 协议下）。
更关键的是：组件文档页通常含交互 demo（比如开关切换、表单输入），<iframe></iframe> 会让这些 JS 绑定失效或作用域错乱，用户点不动、改不了值、看不到实时反馈。
- 文档页里的
data-v-xxx或id="demo-1"在 iframe 内是独立作用域，父模板 JS 拿不到 - 父模板设的 CSS 变量（如
--c-color-primary）不会透传进 iframe - SEO 友好性归零——搜索引擎只索引 iframe 外层 HTML，里面内容基本不可见
CDN 引入的组件库和自动生成文档怎么共存
CDN 引入的组件库（如 Bootstrap、Vant）负责运行时渲染；自动生成的文档负责说明“怎么用”。二者不是替代关系，而是分工协作：一个管执行，一个管解释。
容易踩的坑是文档里写的 class 名（比如 van-button）在模板里没生效，结果查半天发现 CDN 加载的是旧版 Vant，而文档是新版生成的——版本不一致导致 class 名或属性名对不上。
- 文档生成配置里必须锁定组件源码版本，比如
vant.config.mjs中指定version: '4.9.2' - CDN 地址也得同步，例如用
https://unpkg.com/vant@4.9.2/lib/index.css，别用@latest - 文档中所有代码块里的 class、props、事件名，必须和 CDN 加载的 JS 实际暴露的一致，否则就是误导
静态托管环境（如 GitHub Pages）下文档加载失败怎么办
GitHub Pages 不解析 <!--#include--> 或 EJS，也不执行 Node.js 构建脚本，所以文档 HTML 必须是预生成好的、可直接 fetch 的文件，不能依赖服务端拼接。
最稳的做法是把文档生成步骤放进 CI 流程（如 GitHub Actions），每次 push 后自动构建并推送到 docs/ 目录，HTML 模板里用相对路径 fetch('./docs/button.html') 加载。
- 路径必须用
./docs/xxx.html，别用/docs/xxx.html（根路径在 GitHub Pages 下会 404） - 加个 loading 占位符，防止 fetch 失败时页面空白：
<div class="c-doc-placeholder">文档加载中…</div> - fetch 后记得用
DOMPurify.sanitize()过滤 HTML，防止文档源被注入恶意脚本
