文档转HTML
📖 技能介绍
name: 文档转HTML description: 通用多格式文档转 HTML 网页工具。把 Word(.docx) / PDF / PPTX / Excel(.xlsx) / Markdown(.md/.txt) 统一整理成"可导航 + 多层次折叠 + 多条内容分行分条（左侧•圆点）+ 图片内嵌自包含 + 可缩放查看"的单文件 HTML 网页，双击即看、便于分享查阅（图片不依赖外部目录）。适用于任意需要浏览器可看、可折叠查阅的文档场景：培训资料/产品手册/报告/规范/会议纪要/文章/简历等。触发词：文档转HTML、文档转网页、折叠导航、多层次折叠、图片内嵌、自包含HTML、pdf转html、pptx转html、xlsx转html、md转html、docx转html。 agent_created: true license: MIT
通用文档转 HTML 网页（文档转HTML）
概述
把多种源格式（.docx / .pdf / .pptx / .xlsx / .md/.txt）统一转成单文件 HTML 网页：可导航、多层次折叠、多条内容分行分条且每条左侧加蓝色 • 圆点、图片按 源文件原始分辨率内嵌为 base64（自包含，双击即带图，不依赖外部 _media 目录），并且内置可缩放/平移的图片查看器（滚轮缩放、按钮放大缩小/适应/1:1、拖动移动、ESC/点空白关闭）。
适用任意文档场景（不限知识库）：培训资料、产品手册、报告、规范制度、会议纪要、文章、简历等——只要源文件是受支持的格式，一条命令即可产出可分享的网页。
决策树：怎么用
首选 convert.py（统一入口，自动识别格式）：支持 .docx / .pdf / .pptx / .xlsx / .xlsm / .md / .markdown / .txt，按扩展名自动分发到对应提取器，统一渲染成自包含 HTML 网页。一条命令搞定多格式：
python convert.py <文件或目录> [输出目录]
- 单文件 → 同名
.html（输出到同目录或指定目录）；目录 → 递归转换所有支持的源文件。 - 内部管线：
extract.py（格式归一化为DocModel）→render.py（多层级折叠 + 图片内嵌 + 查看器）。
若已有外挂图片的 HTML（图片在
xx_media/目录），用inline_images.py事后批量内嵌为自包含。
convert.py 可选开关：--count（标题后显示数量徽标，默认关）、--no-toc（不生成左侧目录，内容居中铺满）、--items（表格逐行转可折叠卡片 row-item）、--split（按文档最小标题层级拆成多篇）。
脚本清单
convert.py（统一入口，自动识别格式）★ 首选
- 按扩展名分发：
.docx→extract_docx、.pdf→extract_pdf、.pptx→extract_pptx、.xlsx/.xlsm→extract_xlsx、.md/.markdown/.txt→extract_markdown。 - 全部归一为
DocModel后交给render.py渲染，渲染能力（高清内嵌、可缩放灯箱、折叠导航）跨格式复用。
extract.py（格式归一化层，无需单独运行）
把各源格式抽成统一 DocModel（块类型：heading / text / image / table）。新增格式只需写一个 extract_xxx 并登记进 _DISPATCH，渲染逻辑零改动。要点：
- docx：python-docx 抽段落层级 + 表格 + a:blip 图片（原生字节）。
- pdf：pdfplumber 抽文字行（排除表格区）+ 表格（find_tables）+ 内嵌图片（page.images 的流字节，按 magic 判 mime）。
- pptx：python-pptx 抽每页标题（首文本）+ 正文 + 图片（shape.image.blob）+ 表格。
- xlsx：openpyxl 每个工作表 = 一个节（表头=首行），附工作表级图片。
- md/txt：轻量解析 # 标题、| 表格、 图片（本地文件读字节内嵌）、列表项转 • 圆点。
render.py（统一渲染层，无需单独运行）
来源于7w4.net。
消费 DocModel：左侧目录导航（由 heading 建树）+ 多层级 <details> 折叠 + 表格分组检测 + 图片按源文件原始分辨率内嵌（不重编码）+ 共享 viewer.py 灯箱。是 docx/pdf/pptx/xlsx/md 共用的唯一渲染实现。
inline_images.py（事后批量内嵌）
python inline_images.py <HTML所在目录>
递归把目录内所有 HTML 的外挂 xx_media/ 图片转 base64 data URI 内嵌。用于把早期外挂版 HTML 收敛为自包含（保持媒体原生分辨率，不重编码）。
viewer.py（共享模块，无需单独运行）
render.py 通过 from viewer import VIEWER_CSS, VIEWER_JS, VIEWER_DIV 注入统一的图片查看器（缩放/平移/关闭）。改查看器只需改这一处，同步生效。
fold_inline_images.py（手工页图片折叠收纳）
python fold_inline_images.py <html> [--label "证书"] [--open] [--selector ".cert-list img"]
手工编写/特殊生成的页面（非 convert.py 正向产物）里常有裸 <img>，想折叠收纳时用它，而非手写 CSS（避免 B8 乱码）。默认把「不在 <details>/.cell-imgs/灯箱内的 img」各自包进 <details class="acc-sub">（默认收起），注入正确 .acc-sub 样式（箭头字面 ▸），幂等可重复运行。
关键规则（务必遵守）
- 图片默认内嵌 base64（单文件自包含 + 原始分辨率）：核心诉求是单文件可分发——双击即带图、便于分享。按源文件原始分辨率内嵌、不重新编码、不改像素（保持源文件最高清原图；个别源图本身小则按原生嵌入，不假放大）。不用外部
_media。凡新建 HTML 都走内嵌；若发现外挂，用inline_images.py收口。 - ⚠️ 体积权衡：原图嵌入会让 HTML 明显变大（如 4032px 大图单文件可到 ~13MB）。这是默认的最高清策略；若需控体积，可在
extract.py各提取器或render.py的图片编码处加长边上限（如缩到 2000px）再取舍。 - 图片查看器默认内置（缩放/平移）：生成脚本通过共享模块
viewer.py注入自包含查看器——点图打开全屏，滚轮以光标为中心缩放，底部 ＋/－/适应屏幕/1:1 按钮 + 百分比，鼠标/触屏拖动移动，双指捏合缩放，点空白或 ESC 关闭。无需事后处理；所有内容<img>都带onclick="zoom(this)"。 - 分组列自动检测：第 0 列唯一值数
≥ 2 且 < 行数（即首列存在重复值）判为分组维度，按该列做一级折叠块、主键顺延下一列。唯一值=1（整列相同）不分组——只有真正存在多个不同值时才折叠分组，避免单列全同的表被无意义拆分。单行表不触发。 - 图片列二次校验：表头含「图」字不能盲判为图片列，必须验证该列数据行真的含
a:blip图片，否则整列文字会被当图片丢弃（「出图周期」表头含"图"字、纯文字，曾致整列内容丢失）。 - 序号补 N.1：大纲里顶层节 N 下的无编号纯文字条目按顺序补
N.1/N.2…；已带N.M保持原编号；N.M.K三级挂最近二级条目。 - CSS 转义陷阱：折叠箭头用字面字符
▸(U+25B8) 写入 CSScontent，圆点用字面•(U+2022)。禁止单反斜杠\25B8——Python 会当八进制转义（\25→0x15 控制符），写进 HTML 后箭头位变乱码（B8）、圆点变不可见控制符。双反斜杠\\25B8虽能侥幸正确显示，但不如字面字符稳，统一用字面字符。 - 多表节：一节多表时收集进
tables列表，每张表独立成 block，避免只存最后一张表导致内容丢失。 - 计数徽标默认关闭：分组/逐项标题后的数量徽标（如「3」「5」）默认不渲染，需显式
--count才开启。核心偏好是「标题不带数字」——用户未明确要求计数时，一律不显示数量。 - 折叠层次内容驱动、不写死：分组表格自动形成「合并项(sub-sec)→子表/逐项(row-item)」多层次；配合
--items可把平面表也逐行转可折叠卡片(row-item)。层次随数据实际结构灵活生成，而非固定层数。
踩坑记录（反思）
- B8 乱码：CSS
content:"\25B8"在 Python 源码被八进制转义 → 改用字面▶/•。 - 分组误判：原阈值把轻微重复列误判分组 → 收紧为
≤ 行数//2；且唯一值=1 仍按分组（见规则 3）。 - 图片列误判：表头含"图"字但纯文字（出图周期）→ 二次校验
a:blip（见规则 4）。 - 压缩内嵌≠高清：早期把图缩到 1600px / JPEG q82 内嵌，看似"内嵌自包含"，实则丢了源文件原图清晰度；
_media文件夹里是与其逐字节相同的压缩副本（并非高清），真正高清一直在源文件。→ 现改为按源文件原始分辨率内嵌、不重编码（规则 1）。若已生成旧版，需用感知哈希把压缩内嵌图映射回源文件原图池（同图多分辨率取最大者）重嵌。 - 灯箱只能弹不能缩放：原灯箱只有"居中显示大图 + 点空白关闭"，无缩放/平移，部分图片还漏了
onclick→ 点了没反应。→ 现抽出共享viewer.py，生成脚本默认内置可缩放/平移查看器（规则 2），且对所有内容<img>补onclick="zoom(this)"。 - 单格式耦合导致难扩展：早期直接读 docx，新增 PDF/PPTX/XLSX/MD 要重写整套渲染 → 重构为「
extract.py归一化层（各格式→DocModel）+render.py统一渲染层 +convert.py调度」。新增格式只写extract_xxx并登记_DISPATCH，渲染零改动，高清内嵌/灯箱/折叠全部复用。 - PDF 图片提取坑：
pdfplumber的page.images给的是 xobject 流，get_rawdata()才是编码字节；需按文件头 magic（ffd8→jpeg / 89504e→png / II/MM→tiff）判 mime，FlateDecode 裸流用 Pillow 包成 PNG，否则图片内嵌失败或 MIME 错。 - XLSX 图片归属：
openpyxl图片挂在工作表级（ws._images），无法精确对应单元格 → 统一作为该工作表节末尾的图片块附上，不强行塞进单元格。 - Word 占用写不进源：改源 docx 段落/序号前，先探测是否被 Word 锁（磁盘有
~$xxx.docx临时文件或PermissionError）。锁住时先改 HTML 应急生效，关 Word 后再把改动写回源 docx 并重跑固化为真"按原文"，否则重跑会被还原。 - 计数偏好（标题不带数字）：用户明确要求各栏目标题后不带
3/5之类的计数数字。→ 默认不渲染数量徽标，需计数时显式--count开启（规则 8）。 - B8 乱码复发：即便知晓规则 6，手工注入 CSS（如图片折叠
.acc-sub）时仍易写成content:"\25B8"被 Python 八进制吃掉成乱码。→ 一律用字面▸；fold_inline_images.py已内置正确写法，手工页优先用它而非手写 CSS。
完整工作流（接任务到交付）
- 探测：确认源格式与是否被占用——docx 看表/段落层级/图/
~$锁文件；pdf/pptx/xlsx 看页数/工作表；md 看标题层级。被 Word 占用则先改 HTML 应急、记录待固化（见踩坑）。 - 运行转换：
python convert.py <源文件或目录> [输出目录]，自动识别格式；目录模式递归转换所有支持的源。 - 图片内嵌校验：
grep -c "_media" <html>应为 0，grep -o "data:image"应 > 0；且图片为源文件原图分辨率（非压缩版）。 - 查看器校验：HTML 含
id="lbstage"、function lbZoom；所有内容<img>带onclick="zoom(this)"（点图能打开、滚轮/按钮可缩放、拖动可移）。 - 结构校验：目录项、导航项、分组块、折叠层级是否符合预期（不同格式结构语义不同：docx 多表格分组、pptx 按页、xlsx 按工作表、md 按
#标题）。 - 交付：直接分享
.html单文件即可，图片已内嵌其中。
依赖（隔离 venv）
PY="C:/Users/Administrator/.workbuddy/binaries/python/versions/3.13.12/python.exe"
VENV="C:/Users/Administrator/.workbuddy/binaries/python/envs/default"
[ ! -f "$VENV/Scripts/python.exe" ] && "$PY" -m venv "$VENV"
"$VENV/Scripts/pip.exe" install python-docx pillow pdfplumber python-pptx openpyxl
运行："$VENV/Scripts/python.exe" scripts/convert.py <源文件或目录> [输出目录]
🤖 AI 评测
这是一个功能完善、实用性强的文档转换工具，能够将 Word、PDF、PPT、Excel 等多种格式统一转成带导航和图片的可浏览网页，质量稳定可靠。主要优点是生成的文件自带折叠目录和高清图片查看器，无需额外软件就能直接分享使用；文档清晰，踩坑记录详细，开发质量较高。美中不足的是目前缺少自动化测试覆盖，极端情况下可能有偶发错误，但日常使用体验良好。总体推荐。
