【GitHub探索】ebook-boilerplate——批量转markdown为PDF和电子书

正值十一假期，近期准备把自己的python笔记精编整理，做一个pdf电子书。在调研如何把多个markdown文档转化为单个pdf的时候，试了很多种方法。最后找到了最佳方案，也就是本文的主角，由phodal前辈整理的电子书生成项目ebook-boilerplate。这个项目不仅支持批量转markdown为pdf，而且还支持转成ebook等多种格式。

使用这个项目的时候，也踩了一些坑，需要做一些额外的配置。以笔者的场景为例，电子书生成环境是Ubuntu22，需要转化一堆中文的markdown。clone了这个项目之后，除了ebook-boilerplate本身README.md里描述的内容之外，实际还需要留意以下环节：

第一块是pandoc跟texlive的环境，最好是官网下载最新的版本，apt里面的版本已经过时了。尤其是texlive，apt拿到的版本很多宏库都没有，得要用官网最新的install脚本才会自动把各种package都装上。

然后是生成pdf的操作里，需要指定一种支持中文的tex-engine，笔者是选择了xelatex。需要在makefile的pandoc生成pdf那块做修改：

pdf: markdown
	pandoc -s $(filename).md -o $(filename).pdf \
		--title-prefix $(title) \
		--listings -H listings-setup.tex \
		--template=template/template.tex \
		--pdf-engine=xelatex \  # 加这一行，声明pdf-engine
		--toc

之后，markdown生成pdf的步骤，实际是把所有markdown内容按文件名顺序（可以用数字标识组织一下）拼接在一起，然后用toc按照markdown的标题文本（h1、h2之类）生成目录，最后再生成pdf。这里有一个问题，就是我们每一章都要分页，而在markdown里标识分页的html标签<div STYLE="page-break-after: always;"></div>在tex-engine下面，是没法出分页的效果的。这种情况下的解决方案是：把这个标签换成\newpage，这样tex-engine就能识别了。也就是说，你的md文件的内容应该是：

# 1.1 xxx.md

# 上面忽略你的markdown正文

\newpage

再之后，我们可以修改listings-setup.tex以及template/template.tex里的内容，去修改代码高亮跟正文的排版参数。以笔者的观感为例，这里面的内容编辑了以下几个部分：

• 代码高亮，即listings-setup，basicstyle设置字号为\small
• template.tex里，取消对于中文刊物习惯的设置，正文字号为9pt，行距调整为1.1。
• xelatex下，中文字体为Noto Sans CJK SC，默认字体为Helvetica。当然，如果你喜欢衬线Serif字体，也都得调整成衬线的形式。

最后就是各种调试勘误，生成最后的文档了。

当然，一开始所说的，笔者精心整理的python笔记，现在也已出炉。各位读者可以阅读这篇文章以获取资源。