Pandoc EPUB 电子书制作实战指南：从一行命令到完整书籍出版

Pandoc EPUB 电子书制作实战指南从一行命令到完整书籍出版【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本指南基于 pandoc 官方文档《Creating an ebook with pandoc》仓库内 doc/epub.md展开讲解如何用 pandoc 将 Markdown 文稿一键转换为 EPUB 电子书并覆盖真实书籍的批量转换、样式定制、字体嵌入与数学公式处理等完整工作流。读完本文你将掌握从零编写源文件、处理本地图片、合并多章节书稿、配置 EPUB 元数据以及解决 EPUB2/EPUB3 数学公式兼容性问题的全套实战技能。一、背景pandoc 的 EPUB 支持EPUB 是目前最主流的电子书开放格式可在 iPad、Nook 以及大量智能手机等电子书阅读器上直接阅读。自 pandoc 1.6 版本起pandoc 原生支持生成 EPUB 输出这意味着从 Markdown 到电子书只需要一条命令。在当前仓库中EPUB 输出由两个独立的 writer 实现分别对应两种规范版本见 src/Text/Pandoc/Writers/EPUB.hs#L17writeEPUB2—— 面向 EPUB 2.0 规范命令行-t epub2writeEPUB3—— 面向 EPUB 3.0 规范默认的-t epub3默认情况下pandoc ... -o out.epub直接产出 EPUB3 文件。如果你的阅读器较老或发布平台要求 EPUB2则需显式指定-t epub2。补充说明EPUB 文件也可转换为 Kindle 格式。Amazon 曾提供命令行工具 KindleGen支持 Linux、macOS、Windows但该工具已停止维护Windows/macOS 上也可用图形界面的 Kindle Previewer 完成转换。本文后续步骤生成的.epub文件均可直接上传到电子书阅读器使用。二、玩具示例五分钟生成你的第一本 EPUB2.1 编写源文件用文本编辑器创建一个文件mybook.txt内容如下% My Book % Sam Smith This is my book! # Chapter One Chapter one is over. # Chapter Two Chapter two has just begun.这里用到的是 pandoc Markdown 的标题块title block语法以%开头的前几行分别表示书名和作者标题块之后空一行再开始正文。如果你更喜欢结构化元数据也可以直接用 YAML 元数据块见本文第六节两种方式 pandoc 均支持。2.2 一条命令完成转换pandoc mybook.txt -o mybook.epub就这么简单。pandoc 会自动识别.epub扩展名并选择合适的 writer把标题块写入 EPUB 的 Dublin Core 元数据、按#一级标题拆分章节、生成目录toc最终产出一个完整的mybook.epub文件。你可以立即把它上传到电子书阅读器试读。2.3 本地图片自动打包如果 Markdown 源文件中包含指向本地图片的链接例如Julietpandoc 会自动把这些图片嵌入生成的 EPUB 中无需任何额外参数。从源码看这一行为由 src/Text/Pandoc/Writers/EPUB.hs#L1228-L1231 中的transformInline实现它会遍历文档内的Image节点通过modifyMediaRef将图片文件复制进 EPUB 的媒体目录并重写图片引用路径。只有带有external属性的链接如网络图片 URL才会被跳过。三、真实书籍实战把 Pro Git 全书转换成 EPUB玩具示例之外更常见的是把一整本书的 Markdown 书稿转换成电子书。本节约 20 分钟即可完成一个真实案例——把 Scott Chacon 使用 pandoc 的 Markdown 变体编写、并以知识共享许可发布的《Pro Git》一书转为 EPUB。3.1 获取书稿《Pro Git》的 Markdown 源码发布在其开源仓库中先克隆整个仓库git clone https://github.com/progit/progit.git如果你没有安装 git也可以在仓库页面点击 Download Source以 zip 或 tar 归档形式下载同样的文件。该命令会在本地创建一个名为progit的工作目录。英文版书稿的 Markdown 源码位于en子目录cd progit/en3.2 理解章节文件结构可以看到书的每一章都放在一个独立目录中每章是单独一个文本文件01-introduction/01-chapter1.markdown 02-git-basics/01-chapter2.markdown 03-git-branching/01-chapter3.markdown ...这种一章一文件的组织方式与 pandoc 的--split-level机制天然契合合并转换时pandoc 会在指定层级的标题处把整本书拆分为多个章节 XHTML 文件。当前仓库中--split-level的默认值为1见 src/Text/Pandoc/App/Opt.hs#L859即每个#一级标题对应 EPUB 中的一章内部以ch001.xhtml、ch002.xhtml的形式命名章节文件见 src/Text/Pandoc/Writers/EPUB.hs#L1256-L1257。3.3 修复图片占位符Pro Git 的书稿在发布前经过了一些后处理例如插入图片。原始书稿中图片以占位符形式存在Insert 18333fig0101.png Figure 1-1. Local version control diagram.而真实的图片文件名为18333fig0101-tn.png存放在仓库的figures子目录下。为了得到纯 Markdown 书稿需要把这个占位符改成 Markdown 图片链接。pandoc 会把仅含一张图片的段落视为带标题的图figure标题取图片的 alt 文本这正好符合需求Figure 1-1. Local version control diagram.可以用一条 Perl 命令批量完成所有章节文件的替换-i原地修改-0pe以整文件为单位进行正则替换perl -i -0pe \ s/^Insert\s*(.*)\.png\s*\n([^\n]*)$/!\\2/mg \ */*.markdown该命令会直接修改文件。如果操作失误无需担心备份问题——仓库本身就是 git 版本库随时可以恢复原始文件git reset --hard3.4 编写书籍元数据接下来需要一个包含 pandoc YAML 元数据块的文件title.txt--- title: Pro Git author: Scott Chacon rights: Creative Commons Non-Commercial Share Alike 3.0 language: en-US ...这些字段会被映射为 EPUB 的 Dublin Core 元数据dc:title、dc:creator、dc:rights、dc:language等。各字段的详细说明与更多可用字段identifier、publisher、date、subject等见 MANUAL.txt 的 EPUB 元数据章节。3.5 合并所有章节生成 EPUB把标题页文件与全部章节文件一起交给 pandoc一次生成整本电子书pandoc -o progit.epub title.txt \ 01-introduction/01-chapter1.markdown \ 02-git-basics/01-chapter2.markdown \ 03-git-branching/01-chapter3.markdown \ 04-git-server/01-chapter4.markdown \ 05-distributed-git/01-chapter5.markdown \ 06-git-tools/01-chapter6.markdown \ 07-customizing-git/01-chapter7.markdown \ 08-git-and-other-scms/01-chapter8.markdown \ 09-git-internals/01-chapter9.markdown完成progit.epub已经是一本完整的电子书可以直接上传到阅读器阅读。3.6 幕后EPUB 是如何组织起来的从源码视角看pandoc 生成 EPUB 时会做以下几件事打包容器以 OCF 容器规范组织文件正文默认放在名为EPUB的内容子目录中optEpubSubdirectory默认值为EPUB见 src/Text/Pandoc/App/Opt.hs#L861可用--epub-subdirectory修改生成章节 XHTML每个章节按--split-level拆分为独立 XHTML 文件并写入spine播放顺序注入媒体所有本地图片、视频、音频等媒体文件统一收集到媒体目录mediaTypeOf负责识别媒体 MIME 类型见 src/Text/Pandoc/Writers/EPUB.hs#L1248-L1253生成导航EPUB3 使用nav文档提供目录导航源码中通过propertiesnav属性标记见 src/Text/Pandoc/Writers/EPUB.hs#L650。四、定制外观样式与字体4.1 用--css指定样式表使用--css选项可以为整本书指定 CSS 文件pandoc mybook.txt -o mybook.epub --css style.css如果不指定pandoc 使用内置的默认样式。该默认样式就是仓库中的 data/epub.css你可以把它复制出来作为自定义样式的起点。这份样式表虽然精简但已经处理了正文排版、标题分页、代码块、表格、脚注、任务列表等常见元素值得注意的细节包括h1强制page-break-before: always保证每章从新页开始img { max-width: 100% }防止图片溢出屏幕内置了light-dark()色彩方案支持配合color-scheme: light dark阅读器切换到深色模式时文档会自动适配深色调并为不支持该特性的阅读器保留了浅色回退值包含了标题页h1.title、p.author、p.date与封面#cover-image相关样式。4.2 嵌入字体EPUB 阅读器普遍支持字体嵌入可以让电子书在不同设备上呈现一致的排版效果。使用--epub-embed-font选项嵌入字体文件pandoc mybook.txt -o mybook.epub \ --epub-embed-font special.otf \ --epub-embed-font headline.otf该选项可重复使用以嵌入多种字体参数解析见 src/Text/Pandoc/App/CommandLineOptions.hs#L1020-L1027。注意需要在 CSS 中通过font-face声明并使用这些字体嵌入才有实际效果。五、数学公式EPUB3 MathML 与兼容方案5.1 EPUB3 的 MathML 输出pandoc 的 EPUB3 writer 会把 LaTeX 数学公式渲染为MathML。EPUB3 规范要求阅读器支持 MathML但遗憾的是实际支持它的阅读器并不多。5.2 面向 EPUB2 与旧阅读器的公式方案如果你的目标是 EPUB2 输出pandoc -t epub2或者需要兼容不支持 MathML 的阅读器有两种替代方案--webtex选项调用一个 Web 服务把 TeX 公式转换为图片。源码中的transformInline会取 WebTeX 服务的 URL将公式编码后拼接成图片地址并下载进 EPUB 的媒体目录见 src/Text/Pandoc/Writers/EPUB.hs#L1232-L1237最后以img形式嵌入正文--gladtex选项在本地把公式转换为 SVG 图片由本机安装的 GladTeX 工具完成不依赖网络。# EPUB2 输出 公式转图片 pandoc mybook.txt -t epub2 -o mybook.epub --webtex # 或使用本地 GladTeX 转换 pandoc mybook.txt -o mybook.epub --gladtex值得一提的是无论 GladTeX 还是 WebTeX 方案pandoc 都会把公式的LaTeX 源码作为图片的替代文本alt text写入这对使用屏幕阅读器的视障用户非常友好公式图片无法加载时也能看到原始 LaTeX 文本。六、进阶完整元数据与封面控制6.1 用--epub-metadata指定 Dublin Core XML除 YAML 元数据外pandoc 还支持通过--epub-metadata传入一个包含 Dublin Core 元素的 XML 文件pandoc mybook.txt -o mybook.epub --epub-metadata meta.xml该选项参数解析见 src/Text/Pandoc/App/CommandLineOptions.hs#L1012-L1018。6.2 YAML 元数据块更丰富的字段推荐的做法是在源文档头部或通过--metadata-file传入独立文件使用 YAML 元数据块。除了title、author、rights、language这些基础字段外pandoc 还支持结构化地描述书籍信息详细字段说明见 MANUAL.txt 的 EPUB 元数据章节例如--- title: - type: main text: My Book - type: subtitle text: An investigation of metadata creator: - role: author text: John Smith - role: editor text: Sarah Jones identifier: - scheme: DOI text: urn:doi:10.234234.234/33 - scheme: ISBN-13 text: urn:isbn:9780000000000 publisher: My Press rights: © 2007 John Smith, CC BY-NC ibooks: version: 1.3.4 ...这些字段与 src/Text/Pandoc/Writers/EPUB.hs#L80-L108 中定义的EPUBMetadata记录一一对应包括identifier支持 DOI、ISBN-13、URN 等多种 scheme、titletype可取main、subtitle、short、collection、edition、extended、creator/contributorrole使用 MARC relator 词表pandoc 会尝试把 author、editor 等人读值翻译为对应代码、date、lang、subject、description、publisher、source、rights等。此外还支持ibooks、calibre等平台专属元数据字段以及accessibility系列无障碍元数据accessMode、accessibilityFeature等见 src/Text/Pandoc/Writers/EPUB.hs#L103-L107。6.3 封面图片与标题页--epub-cover-image FILE指定封面图片文件pandoc 会将其写入 EPUB 元数据cover-image属性EPUB3 中对应propertiescover-image见 src/Text/Pandoc/Writers/EPUB.hs#L664并在正文前生成封面页--epub-title-page true|false控制是否生成标题页默认值为true见 src/Text/Pandoc/App/Opt.hs#L865。标题页/封面的 XHTML 结构由模板 data/templates/default.epub3 控制其中coverpage分支使用内联 SVG 呈现封面图片titlepage分支则输出title、subtitle、author、publisher、date、rights等元数据。七、小结回顾整个工作流pandoc 让电子书制作变得极其轻量入门任意 Markdown 文件 pandoc in.txt -o out.epub即可成书本地图片自动打包实战多章节书稿按文件顺序合并转换通过--split-level或已弃用的--epub-chapter-level控制章节拆分粒度默认在#一级标题处拆分外观--css自定义样式默认样式见 data/epub.css--epub-embed-font嵌入字体公式EPUB3 用 MathML兼容方案用--webtex在线转图或--gladtex本地转 SVG且都会保留 LaTeX 源码作为替代文本元数据--epub-metadata传入 Dublin Core XML或使用 YAML 元数据块声明结构化字段--epub-cover-image、--epub-title-page控制封面与标题页。如需了解全部 EPUB 相关选项如--epub-subdirectory调整内容目录名、--split-level的取值约束等可查阅 MANUAL.txt 中对应的选项说明以及 src/Text/Pandoc/App/CommandLineOptions.hs#L984-L1061 的选项解析实现。现在就试着把你自己的一份 Markdown 文档变成第一本电子书吧。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考