# Paper To HTML > 把一篇学术论文 PDF 精读并整理成一份**精美的中文 HTML 解析文档**——用 MathJax 正常渲染论文公式、嵌入从 PDF 提取的原文配图，并在原文之上加入"直觉/机制/批判/对读者启发"的理解。当用户说"把这篇论文整理成精美HTML""生成带公式和配图的论文解析网页""论文→HTML精读""做成可视化解读HTML"或给出论文 PDF 要求产出 HTML 文档时使用。本 skill 固化了一套「读透→核对→提图→分块写→验证」的产出流程与一套现成的 HTML 设计系统（侧栏目录、明暗主题、七种 callout、公式块、数据表、ASCII 图）。 - Skill: `jx1100370217/paper-to-html` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add jx1100370217/paper-to-html` - Raw SKILL.md: https://api.skillmd.com/api/skills/jx1100370217/paper-to-html/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: jx1100370217 (https://skillmd.com/u/jx1100370217) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/jx1100370217/paper-to-html --- # 论文 → 精美中文 HTML 精读 把一篇论文"讲透"，并产出一份**单文件、可直接双击打开的精美中文 HTML**：公式用 MathJax 正常显示、配图是从原 PDF 裁出的真图、内容在忠实原文之外叠加你的理解。这是 `paper-deep-read`（产出 Markdown）的 **HTML 产出版**，方法论一致，多了「公式渲染 + 配图提取 + 网页设计」三件事。 ## 核心理念（四根支柱，缺一不可） 1. **建立直觉** —— 为什么做这个、核心 insight 是什么，用最直白的话和类比讲清楚； 2. **拆透机制** —— 每个公式逐项、每行算法逐句翻译成"人话"，配「公式人话版」盒子； 3. **批判审视** —— 真正的创新定位、优势、局限与存疑，**有内容、不套话**； 4. **联系读者** —— 结合读者自己的研究方向（看对话/`MEMORY.md`），给出**具体**的可迁移/结合/互补点。 > 不套固定模板填空。先理解论文，再针对这篇的特点设计最能讲透它的结构与配图。 ## 交付物形态（硬约束） - **单个 `.html` 文件** + 同级 `assets/` 目录（放裁好的配图 `fig1.png…figN.png`）。 - 命名延续用户既有习惯（观察同/邻目录），常见：`英文名_中文描述_精读.html` 或 `_可视化解读.html`。 - **公式**：MathJax（CDN），行内 `\( \)`、独立 `\[ \]`；每个关键公式配一段「人话版」+ 逐符号表。 - **配图**：从 PDF 渲染裁剪的真图，中文图注自己写（解读而非照抄）。 - **排版**：直接复用 `references/html-template.html` 的设计系统——hero 头图、粘性侧栏目录 + 滚动高亮、明暗双主题、七种彩色 callout、可横滚数据表、ASCII 流程图/一页纸框、响应式。 ## 工作流程（按此推进，每步都验证） ### Step 1 — 定位与勘察 - 确认 PDF 路径与输出目录；`pdfinfo | grep -iE "pages|page size"` 查页数与页面尺寸。 - 观察同/邻目录已有文件，沿用命名习惯（`.html` 后缀）。 ### Step 2 — 通读建立整体理解 - 用 Read 工具直接读 PDF（按页范围，单次 ≤20 页），图文一起看：动机、方法、实验、结论。 ### Step 3 —【关键】提取文本核对精确细节 - `pdftotext -layout out.txt` 提取全文。 - **务必用文本核对所有表格数字、公式、算法伪代码、超参数**——看 PDF 图像极易看错数字（0.88↔0.68、消融勾选行看反）。`-layout` 对双栏表格最友好。 - 抄准所有关键常量：超参、阈值、数据集规模、指标、耗时、GPU 型号、骨干/基线名。写进 HTML 前以这份文本为准。 ### Step 4 —【关键】提取配图 - **严格按 `references/figure-extraction.md` 执行**：整页高清渲染(`pdftoppm -r 200`) → 按图区裁剪(`-x -y -W -H`) → **逐张 Read 查看校验** → 不满意重裁 → 重命名 `figN.png`、清理整页渲染。 - 别用 `pdfimages`（复合图会碎）。别装 ImageMagick（`pdftoppm` 自带裁剪足够）。 - 裁好的每张图**必须肉眼看过**，坐标估错时不看图，最后就是残图。 ### Step 5 — 设计"讲透"的结构（针对本文，不套模板） - 想清楚这篇的"灵魂句"（一句话核心洞察）。 - 据论文类型裁剪骨架：理论型重公式推导；系统/工程型重模块协同与实验落地；benchmark 型重指标与设置。 ### Step 6 — 用模板分块写 HTML - **以 `references/html-template.html` 为起点**：把它复制为目标 HTML（`cp` 或用 Write 复制内容），替换 hero/title/目录占位符。模板里 `` 注释块是组件速查（照抄标签），写完删掉它。 - **分块写作**：模板末尾有唯一锚点 ``。用 `Edit` 把锚点替换为「新章节 + 新锚点」，逐块追加（每块一两个大章节，保证高密度）；最后一块替换掉锚点收尾。 - 每章一个 `
`，id 与侧栏目录 `href` 对应（scroll-spy 靠它高亮）。 - 配图用 `
中文解读
`。 ### Step 7 — 验证完整性（写完必做） 用 bash 核对： - `grep -c CONTINUE_MARKER ` 应为 **0**（锚点清零）。 - ``/``/`` 各 **1**、scroll-spy 脚本 **1**（分块续写易残留重复收尾，务必查）。 - **MathJax 配平**：`\( `↔`\)` 数量相等；独立公式数「`\[ `(带空格)」= 「` \]`(带空格)」=`.eq` 块数（注意 `\\[2pt]` 是合法 LaTeX 换行间距，别误计）。 - 图片引用数 = `assets/` 实际张数，且每个 `fig` 文件都存在。 - `grep -oE '

.*

'` 列目录，核对章节齐全无断裂。 - 如条件允许可在浏览器打开抽查公式渲染与配图加载（需用户选浏览器时不必强行打断，静态核对已足够）。 ## 推荐文档骨架（按需裁剪；模板目录已内置这套 id） ``` 〇 阅读导航 —— 不同读者怎么跳读（"你想要X→看第Y章"表 navmap） 一 30秒速览/TL;DR —— 灵魂句(insight盒) + 元信息表 + 贡献清单 二 问题定义 —— 痛点；现有路线困境(递进表);形式化 三 核心洞察 —— 一句话灵魂 + 为什么 + 类比(intuition盒) 四 前置知识补充 —— 补齐论文默认你懂的前置(谱系/流派对比表) 五 方法全景 —— ASCII 数据流图 + 模块职责一览表 + 系统框图 六 模块逐个拆透 —— 每模块:解决什么→怎么做→【公式逐项精读+人话版】→设计哲学 七 数学工具箱 —— 黑话直觉速查表 + 关键雅可比/推导 八 实验全解读 —— 设置;复现关键表格(data表);【解读数字说明什么】;消融;运行时 九 批判性评估 —— 创新定位(系统级vs单点);优势;局限(按影响排序);复现性;叙事模糊点 十 对读者研究的启发 —— 可迁移模块/结合点/互补点/与读者SOTA关系(connect盒) 十一 一页纸总结 —— ASCII 速查框(痛点/灵魂/模块/关键数字/创新/局限/对你) 附录 术语表/符号表/关键引用 ``` ## 质量准则（硬要求） - **公式**：每个关键公式一段「人话版」(plain盒) + 逐符号表(symtable)；说清几何/统计直觉。不渲染数学也能读懂。 - **表格**：用 `table.data` 重现关键数据，`best`=绿色最优、`second`=下划线次优、`ours`=蓝底本文行；重点是**解读**（这数字证明什么、赢在哪输在哪），诚实呈现短板。 - **配图**：真图 + 中文解读图注；复合图讲清每个子图。 - **批判**：区分"系统级组合创新"与"单点算法突破"；局限按影响排序；点出被模糊的叙事（"免标定"≠"免建图/免训练"、"泛化"≠"zero-shot"、自搭弱基线）；留意预印本 typo。 - **联系读者**：从对话/`MEMORY.md` 了解读者方向与在跟的 SOTA，给**具体**迁移/结合建议；对读者项目不确定处措辞"可评估/值得验证"，不武断。 - **语言排版**：默认中文。多用对照表、ASCII 图、callout、速查框提升可读性。 ## 注意事项 / 易错点 - 表格数字、消融勾选行**必须** pdftotext 核对，看图必错。 - 配图**逐张 Read 校验**，坐标估错要重裁。 - 分块续写用唯一锚点；续写 Edit 的 `old_string` 请带上前缀 `
` + 空行 + 锚点的上下文（模板顶部/尾部注释也含锚点字样，否则 Edit 会报"匹配到多处"）。 - **收尾时极易残留重复的 `` 和 scroll-spy 脚本**，Step 7 必查并删重复；写完删掉模板顶部说明注释与尾部组件速查注释块（否则 `grep -c CONTINUE_MARKER` 不为 0）。 - 公式只用 `\( \)`/`\[ \]`，不用 `$`（避免误触发/与正文美元号冲突）；正文/`
` 里的 `<`、`>` 写成 `<`、`>`。
- "讲透"≠"写长"：每句有信息量；但机制/公式/批判/联系读者处要充分展开。
- 若论文涉及读者的具体子领域且读者有相关项目，主动建立联系——这是"精读"与"翻译"的分水岭。