html注释需用结构化标记（如）供脚本提取生成文档，html-to-docx仅做格式转换，不参与文档生成；须严格按@param name type desc格式书写，以结束，配合正则提取并转为静态html文档。
html-to-docx 不是组件文档生成工具——它只做 HTML → DOCX 转换，不解析组件结构、不提取 API、不生成表格或示例。真要实现 HTML 组件的自动化文档生成，得靠注释驱动 + 脚本提取，而不是靠转换库。
HTML 注释怎么写才能被自动识别
必须用结构化注释块，且标记符不能随意发挥。工具（比如自研脚本或 jsdoc 插件）靠正则匹配特定前缀，不是靠语义理解。
- 起始标记必须是
<!-- @component Button -->，不能写成<!-- component: Button -->或漏掉@ - 参数说明用
<!-- @param size string 按钮尺寸 -->，string是类型，不能写成"字符串"或String - 必填项不加标识，可选参数才在 name 后加
?，例如size?；disabled就是必填布尔值 - 每段注释必须以
<!-- @end -->显式结束，否则后续内容会被误吞
怎么把注释变成可读的 HTML 文档页
手写一个 Node.js 脚本比引入框架更可控：它只读 .html 文件、抽注释、转 JSON、套模板、输出静态 HTML。没有构建依赖，双击就能跑。
- 用
fs.readFileSync读取所有.html文件，避免 glob 通配符路径错误 - 正则用
/<!-- @(.*?) -->/gs提取全部注释块，g和s标志缺一不可，否则跨行内容会截断 - 解析时按换行切分，遇到
@param就拆成三段：name、type、desc；空格分割不可靠，要用正则捕获组 - 输出 HTML 时直接用
<table> 渲染 API 表，不要套 <code>React.createElement—— 文档页不需要交互逻辑为什么不用 VitePress 或 Storybook
它们适合“带交互演示的组件库”，但会把简单事搞复杂：本地双击
index.html打不开、import报错、路由跳转失效、样式被重置。你只是想让同事看清disabled是boolean还是string，不是搭一个 SPA。- VitePress 需要
vite dev启动服务，离线查文档就断供 - Storybook 的
args表格本质是运行时反射，对纯 HTML 组件无意义 - 两者都要求组件已注册为 JS 模块，而你可能只有
<my-card></my-card>自定义标签 + 全局 script - 如果已有 Webpack/Vite 项目，再考虑集成；否则，100 行 Node 脚本 + 原生 HTML 更稳
图片和示例代码怎么嵌入才不崩
文档页里的示例不是截图，而是可复制、可运行的真实片段。但直接贴
<my-button size="large">点我</my-button>会出错——缺样式、缺定义、缺 polyfill。- 每个示例区块用
<pre class="brush:php;toolbar:false;"><code class="html"></code> 包裹，语言类名必须准确，否则高亮失效</pre> - 示例里只写最小必要 HTML，不写
外层，避免嵌套冲突 - 图片用相对路径
./assets/logo.svg，别用绝对 URL；生成文档时同步拷贝 assets 目录 - 锚点 ID 必须全小写、无空格/符号，比如
id="button-api"，否则#button-api跳转失败
真正卡住进度的往往不是技术选型，而是注释格式不统一、ID 重复、路径写死。先跑通一个组件的注释→提取→渲染闭环，再批量扩展。
- VitePress 需要
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
