HTML注释需用@component等结构化标签才能被解析为文档元数据，普通注释不生效；html-to-docx仅转换HTML渲染结果，不解析注释；必须先提取注释生成HTML文档页，再转换为DOCX。
直接用 HTML 注释 + html-to-docx 无法实现“组件自动生成”，但能实现“组件文档自动生成”——关键在注释结构化，而非运行时渲染。
HTML 注释必须带 @ 标签才能被解析为文档元数据
工具不会识别普通 <!-- 这是按钮 -->，必须用约定前缀。常见有效标记有：@component、@desc、@param、@end。这些不是 HTML 标准，而是文档生成脚本的解析契约。
-
@component后紧跟组件名（如Button Primary），用于分组和索引 -
@desc只能写一行，多行描述会被截断；换行需用<br>或拆成多个@desc -
@param后格式固定为参数名 类型 说明，中间用空格分隔，不能含括号或逗号 - 所有注释块必须以
@end结尾，否则后续内容可能被误吞
html-to-docx 不解析注释，它只转 HTML 渲染结果
别混淆两个流程：html-to-docx 的作用是把已有的 HTML 字符串转成 DOCX，它不扫描、不提取、不理解 @param 这类注释。想让注释变成文档，得先用另一套脚本（比如正则 + Node.js）把注释提取出来，生成新的 HTML 文档页，再交给 html-to-docx 转换。
- 错误做法：把
<!-- @param size string -->直接塞进要转换的htmlContent里——它会原样输出为不可见注释，DOCX 里看不到 - 正确链路：注释 → 提取为 JSON → 模板渲染成文档 HTML →
HTMLtoDOCX()转 DOCX - 没现成命令一键完成，必须自己写提取逻辑，或用已有工具如
jsdoc（但它只认 JS 注释，不认 HTML 注释）
真实可用的最小可行方案
不用重写整套工具链，用几行正则就能跑通。假设你有一堆带结构化注释的 HTML 文件：
立即学习“前端免费学习笔记（深入）”；
const fs = require('fs');
const { HTMLtoDOCX } = require('html-to-docx');
<p>// 1. 读取文件，用正则提取所有 @component 块
const content = fs.readFileSync('components.html', 'utf8');
const componentBlocks = content.match(/<!-- @component([\s\S]*?)@end-->/g) || [];</p><p>// 2. 简单解析每个块（生产环境建议用更健壮的 parser）
const docsHTML = componentBlocks.map(block => {
const name = block.match(/@component\s+(.+?)\s+@desc/)?.[1] || 'Unknown';
const desc = block.match(/@desc\s+(.+?)\s+(@param|$)/)?.[1] || '';
return <code> <h2>${name}</h2> <p>${desc}</p> </code>;
}).join('');</p><p>// 3. 转 DOCX
const docx = await HTMLtoDOCX(docsHTML);
fs.writeFileSync('components.docx', docx);- 这个脚本不处理嵌套或复杂类型，但能验证注释是否被正确识别
- 如果
@param多于一个，上面正则会漏掉，需改用循环匹配/@param\s+(\S+)\s+(\S+)\s+(.*)/g - 生成的 DOCX 里没有源码，只有文档描述——如需附带源码，得手动拼
<pre><code>块
真正容易被忽略的是：注释位置必须紧贴组件 DOM，且不能跨文件。一个 @component 块只能对应一个 HTML 片段，跨文件引用会导致提取失败——这不是工具限制，是正则解析的天然边界。
