如何使用Pandoc和Markdown创建图书

如何使用Pandoc和Markdown创建图书

照片由Tom Hermans (opens new window)在Unsplash (opens new window)上提供

使用Pandoc和Markdown进行图书创作的艺术 #

自助出版技术书籍 #

Syed Asif

如果你正在寻找一种从Markdown文件创建PDF或EPUB的方法，你可能已经了解到了Pandoc，这是一个多功能的文档转换工具，可以在不同的格式之间转换文件，包括Markdown、HTML、LaTeX等。

Pandoc (opens new window)是一款对于作家、研究人员以及任何处理多种文档格式的人来说非常有价值的工具。它可以无缝地转换文档，因此将Markdown转换为PDF或重新构建HTML成为了一个很好的选择。 不同格式。

Markdown (opens new window)是一种简单的标记语言，广泛用于网页内容、文档和电子书的创建。它以易读性著称，是一种快速、用户友好的文本结构和样式的方式，无需HTML的复杂性。本教程旨在帮助那些想要使用Pandoc和Markdown制作PDF和EPUB的人，特别是那些包含代码片段的技术书籍。

安装Pandoc

安装Pandoc的过程取决于您的操作系统。以下是Linux（Debian/Ubuntu）操作系统的说明。打开终端，并运行以下命令：

$ sudo apt-get update$ sudo apt-get install pandoc$ sudo apt-get install texlive-xetex texlive-fonts-recommended texlive-plain-generic

这些说明涵盖了Debian-based操作系统的基本安装过程。请确保检查官方的Pandoc文档 (opens new window)以获取适用于您操作系统的详细指南。 ## 示例 - 将Markdown转换为PDF

一旦Pandoc在您的系统上运行，可以生成一个没有任何自定义的示例PDF。假设您有一个名为example.md的Markdown文件，并且您想使用Pandoc将其转换为PDF。

这是一个简单的示例：

# Example Document
这是一个Markdown文档的简单示例。
- 它有一个列表。
- 它支持 **粗体** 和 *斜体* 文本。

使用以下命令将Markdown文件转换为PDF：

$ pandoc example.md -o example.pdf

这个命令告诉Pandoc将example.md作为输入（-o代表输出），它将生成一个名为example.pdf的PDF文件。如果要创建一个EPUB文件，可以用example.epub替换example.pdf。

运行命令后，您应该在同一目录下看到一个新的PDF文件example.pdf。

建议在Markdown中使用标题 ## 提升文档结构

自定义章节分页 #

在Pandoc中，您可以通过在Markdown文档中使用特定的标题来插入章节分页。通常，您会使用一个指示新章节开始的标题级别。

# 第一章 这是第一章的内容。# 第二章 这是第二章的内容。# 第三章 这是第三章的内容。

当您使用之前的Pandoc命令将此Markdown文件转换为PDF等格式时，它将识别这些标题作为章节分页，但不会进行页面分页。我们还可以使用自定义的LaTeX模板来自定义章节分页在输出中的外观。

要在每个章节之前强制进行分页（如果您使用类似于# 第一章的标题进行分页），您可以使用Pandoc命令中的-H选项来利用自定义的LaTeX模板。如下所示：

\ 使用自定义的LaTeX模板与Pandoc一起使用可以在格式和样式方面给您带来很大的灵活性。您可以使用Pandoc命令和`-H`选项以及指定的LaTeX模板文件（`chapter_break.tex`）来生成PDF文件：

$ pandoc example.md -H chapter_break.tex -o example_chapter_break.pdf


`-V`选项允许自定义变量值，以调整页面大小、字体、链接颜色等设置。

随着修改的设置数量增加，使用Python脚本来调用Pandoc成为一种更高效的替代方法，可以消除在终端中手动输入冗长命令的需求。

import os import pypandoc

input_dir = "chapters" output_dir = "my_book" output_filename = "book_output.pdf"

确保输出目录存在 #

os.makedirs(output_dir, exist_ok=True)

构建Pandoc选项字符串 #

pandoc_cmd = [ "--include-in-header", "chapter_break.tex", "-V", "linkcolor:b" # 省略其他选项 ]

调用Pandoc进行转换 #

pypandoc.convert_file(input_dir, to="pdf", format="markdown", outputfile=os.path.join(output_dir, output_filename), extra_args=pandoc_cmd)

  • mainfont 用于普通文本
  • monofont 用于代码片段
  • geometry 用于页面大小和边距
  • linkcolor 设置超链接颜色

现在通过一个脚本来调用Pandoc：

$ python3 md2pf.py

语法高亮 #

要自定义代码片段的语法高亮，一种选项是保存一个Pandoc主题并相应地进行编辑。

$ pandoc --print-highlight-style=pygments > pygments.theme

编辑生成的文件，在这个示例中，修改了以下设置： ```

背景色更改为灰色以便于区分代码和文本"background-color": "#f8f8f8",# 斜体设置为false以避免注释问题# 注释文本颜色更改为另一种灰色"Comment": { "text-color": "#9c9c9c", "background-color": null, "bold": false, "italic": false, "underline": false}, #


对于内联代码片段，我们正在更改背景颜色，请将此片段添加到您的新文件（`inline_code.tex`）中：

\usepackage{fancyvrb,newverbs,xcolor}\definecolor{Light}{HTML}{F4F4F4}\let\oldtexttt\texttt\renewcommand{\texttt}[1]{ \colorbox{Light}{\oldtexttt{#1}}}


在您的Python脚本中包含以下选项，并重新生成PDF：

脚本的其余部分如上...# 将pandoc选项构建为字符串pandoc_cmd = [ "--include-in-header", "chapter_break.tex", "--highlight-style", "pygments.theme", "--include-in-header", "inline_code.tex" "-V", "linkcolor:blue", "-V", "geometry:a4paper", " #


要自定义Pandoc中的列表样式，您可以使用自定义的LaTeX模板，将`chapter_break.tex`和`inline_code.tex`重命名为`main.tex`。在您的`main.tex`中添加以下代码：

\usepackage{enumitem}\usepackage{amsfonts}% 一级 \setlist[itemize,1]{label=$\bullet$}% 二级 \setlist[itemize,2]{label=$\circ$}% 三级 \setlist[itemize,3]{label=$\star$}


## 目录

Pandoc提供了一个方便的`--toc`选项，可以在生成的PDF开头无缝地追加一个目录。

使用`--toc-depth`选项自定义目录的深度，默认设置为`3`级。此外，您可以使用`-V toc-title`选项将默认标签`Contents`个性化为您喜欢的内容。

我已经在脚本中添加了更多选项， 以下是脚本的翻译：

其余部分的脚本如上...# 构建pandoc选项作为字符串pandoc_cmd = [ "--toc", "--number-sections", "--resource-path=.", "--metadata-file", "metadata.yml", "--include-in-header", "main.tex", "--highlight-style", "pygments.theme", "-V", "toc-title=目录", "-V", "linkcolor:blue", "-V", "geometry:a4paper", "-V", "geometry:margin=1.8cm", "-V", "mainfont=DejaVu Serif", "-V", "monofont=SauceCodePro Nerd Font", "--pdf-engine=xelatex",]# 其余部分的脚本如上... #


如果您需要模板，请查看[此处的存储库](https://github.com/sydasif/my-pandoc-book)。

本指南作为指南，帮助您在使用Pandoc创建图书的过程中，通过Markdown、Pandoc和创造性的自定义功能，掌握其复杂细节。从语法高亮到目录，释放您的创造力，提升您的写作水平。