抠丁客 抠丁客
项目
编辑 (2024/8/5)

使用 Pandoc 创建电子书

从版本 1.6 开始，Pandoc 可以输出为电子书格式 EPUB。EPUB 电子书可以在 iPad、Nook 和其他电子阅读器上查看，包括许多智能手机。（它们也可以使用仅基于图形用户界面的 KindlePreviewer 在 Windows 和 Mac OSX 上将 EPUB 转换为 Kindle 书籍。KindleGen —— 提供命令行界面并支持 Linux、Mac OSX 和 Windows —— 已被弃用，但互联网上仍可找到其二进制文件。）

这意味着现在制作电子书变得非常容易！我们来尝试一下。

玩具示例

使用文本编辑器创建一个名为 mybook.txt 的文件，内容如下：

% My Book
% Sam Smith

这是我的书！

# 第一章

第一章结束了。

# 第二章

第二章刚刚开始。

要将其转换为电子书只需要一条命令：

pandoc mybook.txt -o mybook.epub

你可以将 mybook.epub 上传到你的电子阅读器上进行测试。

需要注意的是，如果你的 Markdown 文件包含指向本地图片的链接（例如 `# 使用 Pandoc 创建电子书

从版本 1.6 开始，Pandoc 可以输出为电子书格式 EPUB。EPUB 电子书可以在 iPad、Nook 和其他电子阅读器上查看，包括许多智能手机。（它们也可以使用仅基于图形用户界面的 KindlePreviewer 在 Windows 和 Mac OSX 上将 EPUB 转换为 Kindle 书籍。KindleGen —— 提供命令行界面并支持 Linux、Mac OSX 和 Windows —— 已被弃用，但互联网上仍可找到其二进制文件。）

这意味着现在制作电子书变得非常容易！我们来尝试一下。

玩具示例

使用文本编辑器创建一个名为 mybook.txt 的文件，内容如下：

% My Book
% Sam Smith

这是我的书！

# 第一章

第一章结束了。

# 第二章

第二章刚刚开始。

要将其转换为电子书只需要一条命令：

pandoc mybook.txt -o mybook.epub

你可以将 mybook.epub 上传到你的电子阅读器上进行测试。

需要注意的是，如果你的 Markdown 文件包含指向本地图片的链接（例如 ![朱丽叶](images/sun.jpg)），Pandoc 会自动将这些图片包含在生成的 EPUB 文件中。

真实的书籍

为了看看这对真正的书籍意味着什么，让我们将 Scott Chacon 的 《Pro Git》 这本书转换成电子书格式，这本书是他使用 Pandoc 的 Markdown 变种编写的，并且在 Creative Commons 许可下发布。（如果你使用这本书，请考虑购买一份来支持他的优秀工作。）

你可以在它的 GitHub 站点 上找到这本书的 Markdown 源代码。让我们获取整个仓库的副本：

git clone https://github.com/progit/progit.git

这个命令将在你的机器上创建一个名为 progit 的工作目录。英文版书籍的实际 Markdown 源文件位于子目录 en 中，因此首先切换到该目录：

cd progit/en

如你所见，每一章都是单独的文本文件，并且有自己的目录。Chacon 对这些文件进行了一些后处理，例如插入图片。这是一个占位符示例，用于表示图 1-1：

Insert 18333fig0101.png
图 1-1. 本地版本控制系统图。

实际的图像文件名为 18333fig0101-tn.png，位于仓库的 figures 子目录中，这一点可以验证。

为了演示目的，我们需要纯 Markdown 文件，因此让我们将这个占位符改为 Markdown 图像链接。Pandoc 将把只包含一个图像的段落视为带有标题的图，这就是我们想要的：

! [图 1-1. 本地版本控制系统图。](../figures/18333fig0101-tn.png)

我们可以通过 Perl 的一行代码在所有文件中做出这种改变：

perl -i -0pe \
's/^Insert\s*(.*)\.png\s*\n([^\n]*)$/!\[\2](..\/figures\/\1-tn.png)/mg' \
*/*.markdown

这将会修改文件本身。（我们不必担心备份这些文件；如果我们搞砸了，可以使用 git reset --hard 来恢复原始文件。）

好了！现在我们几乎准备好了制作电子书。我们有了各章节，每个章节都在自己的文件中，但我们还需要一个标题。创建一个名为 title.txt 的文件，其中包含 Pandoc 的 YAML 元数据块：

---
title: Pro Git
author: Scott Chacon
rights: Creative Commons Non-Commercial Share Alike 3.0
language: en-US

有关这些字段的更多信息，请参阅 用户手册。

现在运行 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 准备就绪，可以上传到你的阅读器上了。

更改格式

你可以使用 --css 选项来指定书籍的 CSS 文件。默认的 CSS 是最小化的，可以在 GitHub 上找到，或者在你的数据目录中的 epub.css 文件中找到（参见用户手册中的 --data-dir ）。

如果你愿意，甚至可以在 EPUB 中嵌入字体；有关说明，请参阅用户手册中的 --epub-embed-font 部分。

数学

Pandoc 有一个 EPUB3 写手。它将 LaTeX 数学渲染为 MathML，EPUB3 阅读器应该支持 MathML（不幸的是，很少有阅读器真正支持）。

当然，如果你想要输出 EPUB2 格式 (pandoc -t epub2) 或者目标阅读器不支持 MathML，那么你有两个选择：

  1. 使用 --webtex 选项，它会使用网络服务将 TeX 转换为图像。
  2. 使用 --gladtex 选项将数学转换为本地机器上的 SVG 图像。

GladTeX 和 WebTeX 都会在图像的替代文本中添加 LaTeX 公式的源码，从而提高了对盲人用户的可访问性。

在本文档中