mdbook-pdf

中文

博客

基于 mdBook 的后端，用 Rust 编写，基于 无头 Chrome 和 Chrome DevTools 协议 生成 PDF。

安装与使用

由于它是 mdBook 的插件（后端），首先您应该确保 mdbook 可用。

如果您的机器架构是 x86_64，或者您正在使用 Linux 的 ARM64，请检查成功的 GitHub Actions 工作流程/发布，点击最新的一个，然后您可以从工件中获取二进制文件（包括 Windows，Linux，macOS）。

否则，请确保 Rust 编译环境 可用，执行 cargo install mdbook-pdf 编译和安装。

如果您想编译最新版本，请确保 Rust 编译环境可用（cargo build）。运行 cargo install --git https://github.com/HollowMan6/mdbook-pdf.git，或者您也可以克隆仓库并自行编译。（运行 git clone https://github.com/HollowMan6/mdbook-pdf.git，在克隆的文件夹中，运行 cargo build --release，在 target/release/ 获取可执行文件，并将其放入 PATH）

运行时，请确保已安装Google Chrome / Chromium / Microsoft Edge（默认位置安装，配置在PATH或二进制位置）。如果没有安装，并且mdbook-pdf启用了fetch功能（默认情况下未启用，您需要使用cargo install mdbook-pdf --features fetch重新编译以启用），程序将尝试自动下载Chromium浏览器并运行它（注意：如果您使用Linux，如果Chromium依赖项不满足/使用非x86_64架构，可能会出现问题）。

• 在Windows 10及以上版本中，程序可以正常生成PDF，无需安装任何其他软件，因为Microsoft Edge是Windows系统提供的浏览器。当然，考虑到对没有Edge的旧版Windows的支持，您可以在您的计算机上安装Google Chrome。
• 在MacOS中，您需要安装Google Chrome / Microsoft Edge或Chromium。
• 在Linux中，您可以安装Google Chrome / Chromium / Microsoft Edge中的任何一种浏览器。推荐安装Chromium。在您的Linux发行版中，此软件包的名称通常为chromium或chromium-browser（注意：对于18.04之后的Ubuntu，您必须通过snap安装chromium-browser）。

请确保以下内容存在于您的book.toml中

[output.html]

[output.pdf]

并且也请确保[output.html.print]未被禁用（默认情况下应该是启用的，所以如果以下行在您的book.toml中不存在，请不用担心）。

[output.html.print]
enable = true

最简单的book.toml如下所示

[book]
title = "An Example"

[output.html]

[output.pdf]

最后，您可以使用mdbook build命令构建您的书籍，并使用PDF文件，您的PDF文件将在book/pdf/output.pdf中可用。

使用Docker运行

您还可以使用此Docker镜像。

docker run --rm -v /path/to/book:/book hollowman6/mdbook-pdf

如果您的书籍有其他Rust依赖项，您可以在本地机器上安装它们（如果使用Linux），或者如果您不使用Linux，请将相应架构的Linux可执行文件下载到目录中，将~/.cargo/bin替换为您自己的路径。

docker run --rm -v /path/to/book:/book -v ~/.cargo/bin:/mdbook hollowman6/mdbook-pdf

配置

支持自定义PDF纸张方向、网页渲染缩放比例、纸张宽度和高度、页面边距、生成的PDF页面范围、是否显示页眉和页脚以及自定义其格式等。

请查看book.toml和注释以获取[output.pdf]的可用配置的详细信息。

常见问题

1. mdbook-pdf支持Firefox！

目前，虽然Puppeteer根据其文档支持类似Chrome DevTools Protocol Page.printToPDF的功能，但rust-headless-chrome不支持。

2. 断开的链接！

我已经提交了一个Pull Request用于修复mdBook，通过使打印页面（print.html）的链接指向打印页面的锚点，但尚未合并。您可以尝试我的Pull Request分支来实现此功能。

如果您有指向书籍外部的相对链接，请提供静态托管站点URL以便修复。

3. 您能否为PDF添加书签，使其反映目录，就像wkhtmltopdf所支持的那样？

这应该由Chromium实现，并且已经为此创建了一个问题。PDF文件的书签/大纲的基本支持已经可用（mdbook-pdf-outline）。它是用Python编写的，是mdbook的另一个后端，应与mdbook-pdf和在常见问题2中提到的修改后的mdbook（通过cargo install --git https://github.com/HollowMan6/mdBook mdbook安装）一起使用，以修复print.html中的断链。

您可以通过pip install mdbook-pdf-outline安装此后端。

请记住，将以下内容添加到您的book.toml的末尾，在output.pdf之后。

[output.pdf-outline]

如果您想使用与print.html页面中显示的相同的目录，您可以将book.toml保持原样。

如果您想使用与wkhtmltopdf生成的大纲（基于标题生成条目）相似的目录，您可以通过以下方式在您的book.toml中打开like-wkhtmltopdf选项

[output.pdf-outline]
like-wkhtmltopdf = true

最后，您可以在book/pdf-outline/output.pdf中找到大纲版本。

4. 在markdown源中强制页面分页，mdbook-pdf会尊重它！

参考#9，您可以使用以下语法在markdown源中强制页面分页

<div style="page-break-before:always">&nbsp;</div>
<p></p>

5. 在mdbook-pdf中无法渲染我的PDF书籍！

如果您能将其报告给问题跟踪器，提供mdbook-pdf渲染的所有跟踪以及您的book.toml，我将不胜感激。如果它是开源的，您还可以提供您书籍仓库的链接。

RUST_BACKTRACE=full RUST_LOG=trace mdbook build