mdbook-compress

mdBook 后端渲染器，用于生成整个书籍的单个 PDF 文件。

有其他类似项目，但大多数项目以某种方式依赖于 Chrome 来生成 PDF。本项目仅可选地需要安装 Node.js 来进行代码块语法高亮。如果您不想高亮显示，可以在配置文件中指定 highlight = "none"（或者设置 highlight = "no-node" 以使用内置高亮显示器）。

使用方法

要使用此后端，您需要将以下内容添加到您的 book.toml 文件中

[output.compress]

并安装此项目

cargo install mdbook-compress

如果您想保留默认的 HTML 输出，还需要添加 [output.html]，如果它尚未存在的话

生成的 PDF 将存储在 /book/compress/<book-title>.pdf。如果您想查看一个示例 PDF，可以查看 这个，这正是该项目存在的初衷。

配置选项

有一些配置选项。它们都在下面，有一些注释来解释这些选项。所有值都是默认值。

[output.compress]
# You can optionally specify a subtitle. If you don't the PDF
# won't include a subtitle
subtitle = ""
# If you want to use custom fonts, specify them here.
# The value is a path relative to 'theme/fonts' under your book root
font.regular = ""
font.bold = ""
font.italic = ""
font.bold-italic = ""
font.monospace = ""
# Font sizes. Any heading after H6 will use the H6 font size
# All font sizes will become a u8
font_size.title = 12
font_size.h1 = 11
font_size.h2 = 10
# H3 is also used for the subtitle
font_size.h3 = 8
font_size.h4 = 7
font_size.h5 = 6
font_size.h6 = 6
font_size.text = 5
# Page configs
# Page size. One of: A4, US letter, US legal (see below for custom sizes)
page.size = "A4"
page.landscape = false
# Insert a page break between chapters (markdown files)
page.new_pages = false
# Line and margin spacing. Both measured in millimeters (f64 internally)
page.spacing.line = 1.5
page.spacing.heading = 2.0
page.spacing.margin = [20.0, 20.0]
# See the highlighting section below
highlight = "all"

自定义页面大小

如果您需要自定义页面大小，可以像这样给出宽度和高度（x 和 y）尺寸（以毫米为单位）

page.size = { x = "width", y = "height" }

高亮显示

由于需要调用节点命令，使用 highlight.js（mdbook 用于 HTML 的工具）进行代码高亮显示非常慢。为了解决这个问题，本项目使用 syntect 进行任何高亮显示。但是，如果您在书的 主题 目录中指定了自定义的 highlight.js 脚本，代码将使用该脚本。

您仍然可以更改它。配置文件中的 highlight 值可以是以下之一

• "all" (默认)
  当提供highlight.js文件时使用，否则使用syntect
• "no-node"
  即使提供了highlight.js文件，也始终使用syntect。在这种情况下，您可以在主题文件夹中提供.sublime-syntax文件，这些文件将被用于高亮显示。这样，您可以在保持自定义高亮显示的同时，拥有一个比Node更快的替代品
• "none"
  不进行任何高亮显示

值得注意的是，syntect和highlight.js的高亮颜色不同，因为它们是不同的程序

如果您使用syntect，您可以在主题目录中提供一个自定义的theme.tmtheme文件。如果这是一个有效的主题，它将被用于高亮显示。如果不是，则使用主题base16-ocean.light

为什么花费这么长时间？

如果您正在使用自定义的highlight.js文件，这可能会使渲染器变得稍微慢一些。这是由于需要为每个代码块调用Node.js。只有当您需要高亮显示syntect不支持的语言时，才应使用此功能。

还需要添加的功能

• 图像（目前无法使用genpdf实现）
• 自定义highlight.js主题应用（可以应用自定义的syntect主题）

依赖项

如果您想了解不同依赖项的用途，请看这里。描述都是相当一般的，因为更具体的描述会使表格太大。