本文共 5854 字，大约阅读时间需要 19 分钟。
pandoc epub
Pandoc是用于将文件从一种标记语言转换为另一种标记语言的命令行工具。 在我 ，我解释了如何将用Markdown编写的文本转换为网站，幻灯片和PDF。
在后续文章中，我深入地研究 ，展示如何从相同的Markdown源文件生成网站和ePub图书。 我将以我即将使用该过程创建的电子书作为示例。
首先，我将解释用于本书的文件结构，然后介绍如何使用Pandoc生成网站并将其部署在GitHub中。 最后，我演示了如何生成其配套的ePub书。
您可以在我的 GitHub存储库中找到代码。
我用Markdown语法编写所有文章。 您也可以使用HTML，但是当Pandoc将Markdown转换为ePub文档时，引入HTML越多，出现问题的风险就越大。 我的书遵循每文件一章的模式。 使用Markdown标题H1（ ＃ ）声明章节。 您可以在每个文件中放置多个章节，但是将它们放在单独的文件中可以更轻松地查找内容并稍后进行更新。
元信息遵循类似的模式：每种输出格式都有其自己的元信息文件。 元信息文件定义有关文档的信息，例如要添加到HTML的文本或ePub的许可证。 我将所有Markdown文档存储在一个名为parts的文件夹中（这对于生成网站和ePub的Makefile很重要）。 例如，让我们看一下目录，序言和about章节（分为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的格式。
我网站的元信息文件（web-metadata.yaml）是一个简单的YAML文件，其中包含有关作者，标题，权利， <head>标记的内容以及HTML文件的开头和结尾的内容的信息。
我建议（至少）在web-metadata.yaml文件中包括以下字段：
--- title: GRASP principles for the Object-oriented mind author: Kiko Fernandez-Reyes rights: 2017 Kiko Fernandez-Reyes, CC-BY-NC-SA 4.0 International header-includes: - | ```{=html} ``` include-before: - | ```{=html}If you like this book, please consider
spreading the word or buying me a coffee ``` include-after: - | ```{=html}``` ---
需要注意的一些变量：
这些只是一些可用的字段。 看一下HTML中的模板变量（我文章涵盖了LaTeX，但HTML的过程相同）以了解其他内容。
该网站可以作为一个整体生成，导致包含所有内容的页面很长，也可以分成几章，我认为这更易于阅读。 我将解释如何将网站分成几章，以使读者不会被冗长的网站所吓倒。
为了使网站易于部署在GitHub Pages上，我们需要创建一个名为docs的根文件夹（这是GitHub Pages默认用于呈现网站的根文件夹）。 然后，我们需要为docs下的每个章节创建文件夹，将HTML章节放置在它们自己的文件夹中，并将文件内容放置在名为index.html的文件中。
例如，about.md文件将转换为名为index.html的文件，该文件位于名为about （about / index.html）的文件夹中。 以此方式，当用户输入http：// <your-website.com> /左右/，从文件夹的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中获取。 换句话说，Pandoc在<head> HTML标记内添加以下行：
要生成网站，请输入：
make
现在，根文件夹应包含以下结构和文件：
.---parts | |--- toc.md | |--- preface.md | |--- about.md | |---docs |--- assets/ |--- index.html |--- toc | |--- index.html | |--- preface | |--- index.html | |--- about |--- index.html
要在GitHub上部署网站，请执行以下步骤：
您可以在网站上获得更多详细信息。
查看使用此过程生成的 ，以查看结果。
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: @pandoc -s --toc epub-meta.yaml \ $(addprefix parts/, $(DEPENDENCIES:=.md)) -o $(DOCS)/assets/book.epub
ePub目标的命令从HTML版本（您的章节名称）获取所有依赖项，将Markdown扩展名附加到它们，并为它们添加文件夹章节的路径，以便Pandoc知道如何处理它们。 例如，如果$（DEPENDENCIES）仅作为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的过程并不困难，但是有很多细节。 以下概述可能使您更容易理解。
翻译自:
pandoc epub
转载地址：http://eeczd.baihongyu.com/