文档转HTML

为什么需要文档转HTML

团队协作中常积累大量多格式文档：Word 培训手册、PDF 技术规范、PPT 汇报材料、Excel 数据表、Markdown 笔记。这些文档在分享时面临两难：直接发源文件要求接收方安装对应软件（如 Word/Excel/PowerPoint），体验割裂；转成 PDF 又丢失了表格折叠、图片缩放等交互能力，且图片常被压缩或依赖外部 _media 目录，链接失效后图片直接丢失——尤其对包含高清截图的规范文档或产品手册，这种"带图难分享"的问题非常突出。

技能如何工作

这个技能的核心是"格式归一化+统一渲染"的双层管线，解决多格式文档的网页化难题：

1. 格式归一化层（extract.py）

无论源文件是 .docx、.pdf、.pptx、.xlsx 还是 .md/.txt，都先提取为统一的 DocModel 结构（包含 heading、text、image、table 四种块类型）：

• Word：用 python-docx 提取段落层级、表格、原生图片字节；
• PDF：用 pdfplumber 识别文字、表格、内嵌图片流（按 magic 判断格式）；
• PPTX：提取每页标题、正文、图片 blob 与表格；
• XLSX：每个工作表作为一个章节，表头取首行，附带工作表级图片；
• Markdown：解析标题层级、表格、本地图片并内嵌。

2. 统一渲染层（render.py）

消费 DocModel 生成自包含 HTML，核心能力包括：

• 左侧目录：从 heading 块自动生成导航树，点击跳转对应章节；
• 折叠结构：多层级内容可收起/展开，表格支持逐行转卡片；
• 图片处理：所有图片按源文件原始分辨率转为 data:image URI 内嵌，不压缩、不依赖外部目录；
• 内置查看器：通过 viewer.py 注入全屏图片查看器，支持滚轮缩放、按钮调整、拖动平移、ESC 关闭。

3. 调度入口（convert.py）

一条命令完成多格式转换：convert.py <路径>，自动识别扩展名并分发到对应提取器，单文件输出同名 HTML，目录则递归转换所有支持的源文件。还支持 --count（标题带计数）、--no-toc（关闭目录）、--items（表格转卡片）等开关。

注意点与边界

• 图片体积权衡：原图内嵌会让 HTML 体积增大（如 4000px 大图可能导致单文件达 13MB），若需控制体积可在提取阶段限制长边尺寸；
• Word 占用问题：若源 .docx 被 Word 锁定（存在 ~$ 临时文件），直接修改源会失败，可先调整 HTML 应急，待 Word 关闭后再写回源并重跑；
• 格式语义差异：不同格式的结构呈现不同——Word 侧重表格分组、PPT 按页组织、Excel 按工作表分节、Markdown 按标题层级，转换后需对应校验结构是否符合预期。