抓取网页生成电子书(如何从同一个Markdown源文件生成网页和ePub格式的电子书 )

　　抓取网页生成电子书(如何从同一个Markdown源文件生成网页和ePub格式的电子书

)

　　使用 Markdown 和 Pandoc，您可以编写一次并发布两次。

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

　　在这个后续文章 中，我将深入研究 Pandoc 并展示如何从同一个 Markdown 源文件生成网页和 ePub 格式的电子书。我将以我即将出版的电子书《面向对象思维的GRASP原则》为例进行说明。这本电子书是通过以下过程创建的。

　　首先讲解本书使用的文件结构，然后介绍如何使用Pandoc生成网页并部署到GitHub上；最后演示如何生成对应的ePub格式的电子书。

　　您可以在我的 GitHub 存储库 Programming Fight Club 中找到相应的代码。

　　设置书籍结构

　　我使用 Markdown 语法来完成所有写作。也可以使用 HTML 标签，但是 Pandoc 将 Markdown 转换为 ePub 文档时，引入的 HTML 标签越多，出现问题的风险就越大。我的书每章以文件的形式组织，每章的标题都用Markdown的H1标记（#）来声明。您也可以在每个文件中放置多个章节，但将它们放在一个单独的文件中可以更轻松地查找内容并在以后更新。

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

　　这部分书的开头是类似的：

　　# 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文件，标签中收录作者、标题和版权信息，以及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}

<p>If you like this book, please consider

spreading the word or

buying me a coffee

```

include-after:

- |

```{=html}

　　

Designed with ❤️ from Uppsala, Sweden

　　

```

---</p>

　　以下变量需要注意：

　　这些只是一些可用的变量。查看HTML中的模板变量（我的文章Pandoc介绍中描述了如何查看LaTeX模板变量，查看HTML模板变量的过程是一样的）了解剩余的变量。

　　将页面分成几章

　　网页可以作为一个整体生成，这会产生一个收录所有内容的长页面；也可以分成多个章节，我觉得会更容易阅读。我将解释如何将页面分成章节，以便读者不会被长页面吓倒。

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

　　例如，about.md 文件将被转换为名为 index.html 的文件，该文件位于名为 about (about/index.html) 的文件夹中。这样，当用户键入 /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.cs 获得。换句话说，在标签中，Pandoc 会添加这一行：

　　使用以下命令生成网页：

　　make

　　根文件夹现在应收录以下文件结构：

　　.---parts

|    |--- toc.md

|    |--- preface.md

|    |--- about.md

|

|---docs

    |--- assets/

    |--- index.html

    |--- toc

    |     |--- index.html

    |

    |--- preface

    |     |--- index.html

    |

    |--- about

          |--- index.html

   

　　部署网页

　　使用以下步骤将网页部署到 GitHub：

　　创建一个新的 GitHub 存储库并将内容推送到新创建的存储库。在存储库设置中找到 GitHub Pages 部分，然后选择 Source 选项，让 GitHub 使用 master 分支的内容。

　　您可以在 GitHub Pages 上获得有关 网站 的更多详细信息。

　　我的书的网页就是通过上面的过程生成的，结果可以在网页上查看。

　　生成电子书并创建 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:

        @pandoc -s --toc epub-meta.yaml \

        $(addprefix parts/, $(DEPENDENCIES:=.md)) -o $(DOCS)/assets/book.epub

　　用于生成 ePub 格式书籍的命令从 HTML 版本中获取所有依赖项（每个章节的名称），为其添加 Markdown 扩展，并在它们前面加上每个章节的文件夹路径，以便 Pandoc 知道如何处理它。例如，如果 $(DEPENDENCIES 变量只收录“前言”和“关于本书”章节，那么 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 电子书：

　　通过：

　　作者：Kiko Fernandez-Reyes 主题：lujun9972 译者：jlztan 校对：wxy

　　本文由LCTT原创编译，Linux中国荣幸推出