构建PDF

构建PDF#

可以将所有书籍内容构建为一个单独的PDF文件。本页面介绍了几种实现方法。

Warning

PDF构建功能正在积极开发中，可能会有变化或存在错误。

有两种构建PDF文件的方法。

从书籍HTML构建PDF#

可以从书籍的HTML构建一个单独的PDF文件。这首先将书籍的所有内容转换为一个HTML文件，然后通过命令行模拟浏览器将其渲染为PDF。

安装#

系统需要使用 pyppeteer 解析生成的HTML以转换为PDF。

可以通过以下方式安装：

pip install pyppeteer

您可能还需要安装以下软件包（在*nix系统上）：

gconf-service
libasound2
libatk1.0-0
libatk-bridge2.0-0
libc6
libcairo2
libcups2
libdbus-1-3
libexpat1
libfontconfig1
libgcc1
libgconf-2-4
libgdk-pixbuf2.0-0
libglib2.0-0
libgtk-3-0
libnspr4
libpango-1.0-0
libpangocairo-1.0-0
libstdc++6
libx11-6
libx11-xcb1
libxcb1
libxcomposite1
libxcursor1
libxdamage1
libxext6
libxfixes3
libxi6
libxrandr2
libxrender1
libxss1
libxtst6
ca-certificates
fonts-liberation
libappindicator1
libnss3
lsb-release
xdg-utils
wget

构建#

要从书籍的HTML构建单个PDF，请使用以下命令：

jupyter-book build mybookname/ --builder pdfhtml

或

jb build mybookname/ --builder pdfhtml

Warning

如果在构建PDF时遇到“MaxRetryError”并在错误消息中提到SSL，这可能是由于 pyppeteer 在首次下载Chromium时存在错误。请参阅此GitHub评论以获取潜在的修复方法，以及我们在此Jupyter Book问题中跟踪该问题。

通过HTML控制PDF的外观#

由于您使用HTML作为书籍PDF的中介，因此可以通过自己的CSS规则控制HTML的外观和感觉。您对HTML网站所做的多数CSS更改也将在该网站的PDF版本中保留。有关如何定义自己的CSS规则的信息，请参见自定义资源。

要添加仅适用于打印PDF的CSS规则，请使用 @media print CSS模式定义打印特定的规则。这些规则仅在打印HTML时应用，不会出现在非PDF网站中。

例如，要在打印时隐藏右侧的目录，可以添加此规则：

@media print {
    .bd-toc {
        visibility: hidden;
    }
}

右侧的目录将出现在您的实时网站中，但在有人打印您的网站PDF时会被隐藏。

使用LaTeX构建PDF#

您还可以使用LaTeX构建书籍的PDF。此过程要求您在系统上设置 tex。 Jupyter Book将构造一个LaTeX文件，然后使用系统的 latex 构建该LaTeX文件。

本节尝试推荐一些最佳实践。

Note

我们推荐使用 texlive 发行版

jupyter-book 使用 sphinx-jupyterbook-latex 包，该包处理大部分定制的LaTeX基础设施。完整的功能列表可以在 sphinx-jupyterbook-latex 功能列表中找到。

其中一些功能包括：

该包通过提供对在 _toc.yml 中定义的各种结构的支持，实现了 pdf 文件的构建。这还使得 pdf 文件能够以与 html 输出协调一致的方式构建。
jupyter-book 的主文档或根文档在LaTeX中被视为 frontmatter
更新字体以便可以在不破坏LaTeX构建的情况下使用 unicode 字符（默认使用 xelatex）
通过 sphinx.ext.imgconverter 支持 png 和 gif 图像
支持 jupyter-book 标签，如 hide-cell

Note

此功能默认启用，但如果您需要关闭此包，需要在 _config.yml 中添加以下配置：

latex:
  use_jupyterbook_latex: false

安装和设置#

对于基于 Debian 的 Linux 平台，建议安装以下包：

sudo apt-get install texlive-latex-extra \
                     texlive-fonts-extra \
                     texlive-xetex latexmk

或者，您可以安装完整的TeX Live 发行版。

对于 OSX 用户，您可能更倾向于使用 MacTeX，这是一个更用户友好的选择。或者，您也可以使用 TeX Live。

对于 Windows 用户，请安装 TeX Live。

构建#

书籍风格 PDF#

要使用 LaTeX 构建项目的 PDF，请使用以下命令：

jupyter-book build mybookname/ --builder pdflatex

或

jb build mybookname/ --builder pdflatex

Note

如果您只想生成 latex 文件，可以使用：

jb build mybookname/ --builder latex

独立 PDF 文件#

通过启用 --individualpages 选项，可以为项目的每一页构建独立的 PDF 文件，当使用 pdflatex 构建器时。

jupyter-book build mybookname/ --builder pdflatex --individualpages

这个 选项 仅对 pdflatex 构建器启用。

Warning

目前 --individualpages 的实现不利用 sphinx-jupyterbook-latex 引入的改进，而是使用 Sphinx 自带的默认 latex 写入器。我们目前正在努力改进 --individualpages 的构建方式。您可以在这里跟踪进展。

独立的 PDF 文件将位于 _build/latex 构建文件夹中。这些文件将与源文件同名，或者如果嵌套在文件夹中，将以扁平结构命名为 {folder}-{filename}.pdf。

Note

当使用 build 命令指定单个页面时，--individualpages 将自动设置为 True。

我们计划在未来使这一功能生成更适合单页面的 latex 文档（参见 issue #904）。

配置#

更新书籍风格 PDF 文件的名称#

要更新 PDF 文件的名称，您可以在 _config.yml 中设置以下内容：

latex:
  latex_documents:
     targetname: book.tex

这将在 Sphinx 构建 latex_documents 时自动覆盖。通常由 Sphinx 推断，但在使用 jupyter-book 时，在 _config.yml 中命名文件通常更容易找到。

选择不同的 LaTeX 编译器#

当前默认使用 xelatex 来构建 pdf 文件。

Warning

--individualpages 选项目前默认使用 pdflatex。

您可以选择不同的 LaTeX 引擎，如 pdflatex 或 lualatex。例如，要使用 pdflatex 引擎进行 LaTeX 构建，请在您的 _config.yml 中添加以下内容：

latex:
  latex_engine: pdflatex

通过 Sphinx 自定义 LaTeX#

EBP 项目的当前重点是自动化从 myst:md 源构建 pdf 文件的过程，并确保生成的 pdf 文件与 html 输出（在结构上）同步。我们正在积极寻找更多 LaTeX 配置和自定义的方法。

提供的多数自定义功能通过 Sphinx 实现，jupyter-book 的底层构建引擎。

通过 Sphinx LaTeX 设置的配置可以通过 sphinx 部分的 config 传递到您项目的 _config.yml 文件中。

例如，如果您想将 latex_toplevel_sectioning 选项设置为使用 part 而不是 chapter，您可以使用：

sphinx:
  config:
    latex_toplevel_sectioning: 'part'

构建PDF

Contents

构建PDF#

从书籍HTML构建PDF#

安装#

构建#

通过HTML控制PDF的外观#

使用LaTeX构建PDF#

安装和设置#

构建#

书籍风格 PDF#

独立 PDF 文件#

配置#

更新书籍风格 PDF 文件的名称#

选择不同的 LaTeX 编译器#

通过 Sphinx 自定义 LaTeX#