HTML组件自动化文档生成依赖结构化注释与Node.js脚本提取：注释须以@@开始、@@结束，@param后空格分隔name/type/desc，type用string等标准类型，示例含完整HTML结构及CSS引入，输出纯HTML表格。
HTML组件的自动化文档生成，不靠框架、不靠转换库，靠的是结构化注释 + 脚本提取 —— html-to-docx 做不了这事，它只管 HTML → DOCX；VitePress 和 Storybook 也跑不通，它们依赖 JS 模块注册，而你可能只有 <my-card> 标签和全局 script。
HTML 注释怎么写才能被脚本识别
工具不是靠语义理解，而是靠正则硬匹配。写错一个符号，整段注释就废了。
- 起始必须是
<!-- @component Button -->，不能写成<!-- component: Button -->或漏掉@ -
@param后必须空格分隔三部分：name、type、desc，例如<!-- @param size string 按钮尺寸 -->；type写string，别写 “字符串” 或String - 可选参数在
name后加?，如size?；disabled这类没?的就是必填布尔值 - 每段注释必须以
<!-- @end -->显式结束，否则后续 HTML 内容会被误吞进文档块
用 Node.js 脚本提取注释生成 HTML 文档页
100 行以内就能搞定，不用构建工具，双击 gen-docs.js 就能跑出静态 HTML。
- 用
fs.readFileSync读取所有.html文件，避免glob路径通配出错 - 正则必须用
/<!-- @(.*?) -->/gs：g匹配全部，s让.匹配换行，缺一不可 - 对每个匹配块按行切分，遇到
@param就用正则捕获三段（name、type、desc），别用split(' ')—— 类型里有string | number就会崩 - 输出时直接拼
<table>，列固定为Name/Type/Default/Description，不套 React 或模板引擎
示例代码怎么嵌入才真正可用
用户复制粘贴后跑不起来，不是文档失败，是你没给最小可运行环境。
立即学习“前端免费学习笔记（深入）”；
- 每个示例区块用
<pre><code class="html">包裹，且必须包含完整结构：<!DOCTYPE html>、<html>、<head>（含 CSS 引入）、<body>和组件标签 - JS 示例第一行加
// 在组件定义之后执行，防止用户误以为这是初始化入口 - 图片用相对路径或 base64，别放
http://localhost:3000/xxx.png—— 离线打开就 404 - 锚点 ID 必须全小写、无空格和特殊字符，比如
button-size，再配scroll-margin-top避开固定 header
最容易被忽略的是注释块的边界控制：<!-- @end --> 不只是形式，它决定了脚本解析的终止位置；还有示例里的 <head> —— 缺 CSS 就等于缺样式，用户看到的不是组件，是一堆裸标签。
