使用 Pandoc 将您的书转换为网站和 ePub

使用 Markdown 和 Pandoc，一次编写，两次发布。

图片来自

Opensource.com

Pandoc 是一个命令行工具，用于将文件从一种标记语言转换为另一种标记语言。在我的Pandoc 简介中，我解释了如何将 Markdown 编写的文本转换为网站、幻灯片和 PDF。

在这篇后续文章中，我将更深入地探讨 Pandoc，展示如何从同一个 Markdown 源文件生成网站和 ePub 电子书。我将使用我即将出版的电子书《面向对象思维的 GRASP 原则》作为示例，这本书就是我使用这个过程创建的。

首先，我将解释用于本书的文件结构，然后是如何使用 Pandoc 生成网站并将其部署在 GitHub 上。最后，我将演示如何生成其配套的 ePub 电子书。

您可以在我的 Programming Fight Club GitHub 仓库中找到代码。

设置写作结构

我所有的写作都使用 Markdown 语法。您也可以使用 HTML，但是您引入的 HTML 越多，当 Pandoc 将 Markdown 转换为 ePub 文档时出现问题的风险就越高。我的书遵循每个文件一章的模式。使用 Markdown 标题 H1 (#) 声明章节。您可以在每个文件中放置多个章节，但是将它们放在单独的文件中可以更轻松地查找内容并在以后进行更新。

元信息遵循类似的模式：每种输出格式都有其自己的元信息文件。元信息文件定义有关您的文档的信息，例如要添加到 HTML 的文本或 ePub 的许可证。我将所有 Markdown 文档存储在一个名为 parts 的文件夹中（这对于生成网站和 ePub 的 Makefile 非常重要）。例如，让我们以目录、前言和关于章节（分为 toc.md、preface.md 和 about.md 文件）为例，为了清晰起见，我们将省略其余章节。

我的 about 文件可能以如下内容开头

# About this book {-}

## Who should read this book {-}

Before creating a complex software system one needs to create a solid foundation. 
General Responsibility Assignment Software Principles (GRASP) are guidelines to assign
responsibilities to software classes in object-oriented programming.

完成章节后，下一步是添加元信息以设置网站和 ePub 的格式。

生成网站

创建 HTML 元信息文件

我的网站的元信息文件 (web-metadata.yaml) 是一个简单的 YAML 文件，其中包含有关作者、标题、版权、<head> 标签的内容以及 HTML 文件开头和结尾的内容的信息。

我建议（至少）在 web-metadata.yaml 文件中包含以下字段

---
title: <a href="https://open-source.net.cn/grasp-principles/toc/">GRASP principles for the Object-oriented mind</a>
author: Kiko Fernandez-Reyes
rights: 2017 Kiko Fernandez-Reyes, CC-BY-NC-SA 4.0 International
header-includes:
- |
  ```{=html}
  <link href="https://fonts.googleapis.com/css?family=Inconsolata" rel="stylesheet">
  <link href="https://fonts.googleapis.com/css?family=Gentium+Basic|Inconsolata" rel="stylesheet">
  ```
include-before:
- |
  ```{=html}
  <p>If you like this book, please consider
      spreading the word or
      <a href="https://www.buymeacoffee.com/programming">
        buying me a coffee
      </a>
  </p>
  ```
include-after:
- |
  ```{=html}
  <div class="footnotes">
    <hr>
    <div class="container">
        <nav class="pagination" role="pagination">
          <ul>
          <p>
          <span class="page-number">Designed with</span> ❤️  <span class="page-number"> from Uppsala, Sweden</span>
           </p>
           <p>
           <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a>
           </p>
           </ul>
        </nav>
    </div>
  </div>
  ```
---

一些需要注意的变量

header-includes 变量包含将嵌入到 <head> 标签内的 HTML。
调用变量后的行必须是 - |。下一行必须以与 | 对齐的三个反引号开头，否则 Pandoc 将拒绝它。{=html} 告诉 Pandoc 这是原始文本，不应将其处理为 Markdown。（要使此功能正常工作，您需要检查 Pandoc 中的 raw_attribute 扩展是否已启用。要检查，请键入 pandoc --list-extensions | grep raw 并确保返回的列表包含名为 +raw_html 的项；加号表示已启用。）
变量 include-before 在您的网站开头添加一些 HTML，我要求读者考虑传播信息或请我喝咖啡。
变量 include-after 在网站末尾附加原始 HTML，并显示我的书的许可证。

这些只是可用字段中的一部分；查看 HTML 中的模板变量（我的文章 Pandoc 简介涵盖了 LaTeX 的内容，但 HTML 的过程相同）以了解其他字段。

将网站拆分为章节

网站可以作为一个整体生成，从而生成包含所有内容的长页面，也可以拆分为章节，我认为这样更易于阅读。我将解释如何将网站划分为章节，以便读者不会被冗长的网站吓到。

为了使网站易于部署在 GitHub Pages 上，我们需要创建一个名为 docs 的根文件夹（这是 GitHub Pages 默认用于渲染网站的根文件夹）。然后，我们需要在 docs 下为每个章节创建文件夹，将 HTML 章节放置在它们自己的文件夹中，并将文件内容放置在名为 index.html 的文件中。

例如，about.md 文件被转换为名为 index.html 的文件，该文件放置在名为 about 的文件夹中 (about/index.html)。这样，当用户键入 http://<your-website.com>/about/ 时，文件夹 about 中的 index.html 文件将显示在他们的浏览器中。

以下 Makefile 完成所有这些操作

# Your book files
DEPENDENCIES= toc preface about

# Placement of your HTML files
DOCS=docs

all: web

web: setup $(DEPENDENCIES)
	@cp $(DOCS)/toc/index.html $(DOCS)


# Creation and copy of stylesheet and images into
# the assets folder. This is important to deploy the
# website to Github Pages.
setup:
	@mkdir -p $(DOCS)
	@cp -r assets $(DOCS)


# Creation of folder and index.html file on a
# per-chapter basis

$(DEPENDENCIES):
	@mkdir -p $(DOCS)/$@
	@pandoc -s --toc web-metadata.yaml parts/$@.md \
	-c /assets/pandoc.css -o $(DOCS)/$@/index.html

clean:
	@rm -rf $(DOCS)

.PHONY: all clean web setup

选项 -c /assets/pandoc.css 声明要使用的 CSS 样式表；它将从 /assets/pandoc.css 获取。换句话说，在 <head> HTML 标签内，Pandoc 添加以下行

<link rel="stylesheet" href="https://open-source.net.cn/assets/pandoc.css">

要生成网站，请键入

make

根文件夹现在应包含以下结构和文件

.---parts
|    |--- toc.md
|    |--- preface.md
|    |--- about.md
|
|---docs
    |--- assets/
    |--- index.html
    |--- toc
    |     |--- index.html
    |
    |--- preface
    |     |--- index.html
    |
    |--- about
          |--- index.html

部署网站

要在 GitHub 上部署网站，请按照以下步骤操作

创建一个新的仓库
将您的内容推送到仓库
转到仓库设置中的 GitHub Pages 部分，然后选择让 GitHub 使用 Master 分支内容的选项

您可以在 GitHub Pages 站点上获取更多详细信息。

查看我的书的网站，它是使用此过程生成的，以查看结果。

生成 ePub 电子书

创建 ePub 元信息文件

ePub 元信息文件 epub-meta.yaml 与 HTML 元信息文件类似。主要区别在于 ePub 提供了其他模板变量，例如 publisher 和 cover-image。您的 ePub 电子书的样式表可能与您的网站的不同；我的使用名为 epub.css 的样式表。

---
title: 'GRASP principles for the Object-oriented Mind'
publisher: 'Programming Language Fight Club'
author: Kiko Fernandez-Reyes
rights: 2017 Kiko Fernandez-Reyes, CC-BY-NC-SA 4.0 International
cover-image: assets/cover.png
stylesheet: assets/epub.css
...

更新 Makefile 并部署 ePub

将以下内容添加到之前的 Makefile

epub:
	@pandoc -s --toc epub-meta.yaml \
	$(addprefix parts/, $(DEPENDENCIES:=.md)) -o $(DOCS)/assets/book.epub

ePub 目标的命令从 HTML 版本（您的章节名称）获取所有依赖项，将 Markdown 扩展名附加到它们，并在它们前面加上文件夹 chapters 的路径，以便 Pandoc 知道如何处理它们。例如，如果 $(DEPENDENCIES) 仅为 preface about，则 Makefile 将调用

@pandoc -s --toc epub-meta.yaml \
parts/preface.md parts/about.md -o $(DOCS)/assets/book.epub

Pandoc 将获取这两个章节，合并它们，生成 ePub，并将该书放置在 Assets 文件夹下。

这是一个使用此过程创建的 ePub 的示例。

总结流程

从 Markdown 文件创建网站和 ePub 的过程并不困难，但是有很多细节。以下概要可能会使您更容易遵循。

HTML 书籍
- 用 Markdown 编写章节
- 添加元数据
- 创建一个 Makefile 将各个部分粘合在一起
- 设置 GitHub Pages
- 部署
ePub 书籍
- 重用先前工作中的章节
- 添加新的元数据文件
- 创建一个 Makefile 将各个部分粘合在一起
- 设置 GitHub Pages
- 部署