用 pandoc 批量转 HTML5 为 EPUB 最稳，因其正确解析语义标签、自动生成 NCX/OPF、保留 CSS，并需注意编码、标题层级、资源路径、Kindle 兼容性及 epubcheck 验证。
用 pandoc 批量转 HTML5 为 EPUB 最稳
直接用 pandoc 是目前最可靠、兼容性最好、且真正支持批量处理的方式。它能正确解析 HTML5 语义标签（如 <section></section>、<nav></nav>、<aside></aside>），自动生成 EPUB 的 NCX 和 OPF 结构，还能保留 CSS 样式（需额外指定）。
常见错误是直接用浏览器“另存为”或拖拽进 Calibre —— 这些方式常丢章节结构、乱码中文标题、忽略 <meta name="author"> 等元信息。
- 确保 HTML 文件有清晰的层级：用
<h1></h1>做书名，<h2></h2>做章标题，<h3></h3>做节标题（pandoc靠这个生成目录） - 运行命令前先统一编码为 UTF-8（无 BOM），否则 EPUB 在 iOS 上可能显示乱码
- 批量转换示例：
for f in *.html; do pandoc "$f" -o "${f%.html}.epub" --metadata title="$(grep -oP '<title>\K[^<]+' "$f")" --toc --toc-depth=2; done
HTML5 中的 <article></article> 和 <section></section> 必须手动映射到 EPUB 章节
EPUB 3 规范不直接识别 HTML5 语义块；pandoc 默认只按标题（<h1>–<h6></h6>
</h1>）切分章节，<article></article> 或 <section></section> 即使带 id 也不会自动变成独立 EPUB spine 条目。
如果你的网页靠 <article id="ch01"></article> 组织内容，就得在转换时显式告诉 pandoc：
立即学习“前端免费学习笔记（深入）”；
将 Markdown 文章转换为微信公众号兼容的纯 HTML 格式。当用户要求"转成微信格式"、"生成公众号文章 HTML"、"排版到微信草稿箱"、"微信粘贴格式"时触发。输出带内联样式的纯 HTML，微信编辑器可直接渲染，无需额外适配。支持标题、段落、列表、粗体、行内代码、表格、引用块、代码块、配图的完整转换。
- 加
--top-level-division=section强制把每个<section></section>当作一章（前提是它们都含<h2></h2>） - 或用
--epub-chapter-level=2指定从<h2></h2>开始算章节（比默认的<h1></h1>更细） - 若想保留
<article></article>的语义，建议提前用脚本把每个<article></article>包裹成独立 HTML 文件，再批量转
图片路径和相对链接在 EPUB 里极易失效
HTML5 页面中写的 <img src="images/cover.jpg" alt="html5改格式批量网页_导出epub阅读格式法【指南】" > 或 <a href="appendix.html"></a>，在 EPUB 容器内会找不到资源——因为 EPUB 是 ZIP 包，资源必须按 OCF 规范放在特定子目录，且路径要重写。
-
pandoc默认会把同目录图片自动打包进 EPUB，但深层路径（如../assets/）会被忽略，需加--resource-path=.或明确列出：--extract-media=. - 跨 HTML 文件的链接（如从
chapter1.html链到glossary.html）不会自动转成 EPUB 内部引用，必须先合并或用--self-contained（但会导致体积暴增） - 推荐做法：所有资源（CSS、图片、字体）集中放在
resources/下，用pandoc -r html -w epub --resource-path=resources/
中文 EPUB 在 Kindle 设备上显示异常的三个硬坑
不是编码问题，就是字体和 CSS 渲染逻辑冲突。Kindle 对 EPUB3 支持有限，尤其对 @font-face、Flexbox 和 CSS 变量几乎无视。
- 务必禁用自定义中文字体：删掉 CSS 中所有
@font-face声明，改用font-family: "SimSun", "Noto Serif CJK SC", serif;（Kindle 系统自带） - 避免用
rem或vh/vw做字号/间距，全部换为em或绝对单位（pt），例如：body { font-size: 12pt; } - Kindle 不支持
text-align: justify的两端对齐效果，会强制左对齐，若坚持要用，得预渲染成图片（不推荐）
导出后务必用 epubcheck 验证：epubcheck book.epub，报 WARNING 级别的 OPF-019（metadata 缺失）或 NAV-001（导航文件无效）必须修复，否则部分阅读器打不开。
