mdbook-compress

An mdBook backend renderer to generate a single PDF file for a full book.

There are other similar projects, but most rely on chrome in some way to generate a PDF. This project only optionally requires Node.js to be installed for code block syntax highlighting. If you don't want highlighting you can specify that with highlight = "none" in the config (or set highlight = "no-node" to use the built-in highlighter).

Usage

To use this backend, you'll need to add the following to your book.toml file:

[output.compress]

and install this project

cargo install mdbook-compress

If you want to keep the default HTML output, you'll also need to add in [output.html] if it's not already there

The resulting PDF will end up in /book/compress/<book-title>.pdf. If you want to have a look at an example PDF, you can have a look at this one which is the whole reason this project exists in the first place.

Config options

There are a few config options. They're all below and have a few comments to explain things. All the values are the default values.

[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"

Custom page sizes

If you need a custom page size, you can give the width and height (x and y) dimensions in millimeters like this

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

Highlighting

Code highlighting with highlight.js (what mdbook uses for the HTML) is pretty slow because it requires calling a node command. To fix this, this project uses syntect to do any highlighting. However, if you specify a custom highlight.js script in the themes directory of your book, the code will use that.

You can change this though. The highlight value of the config can be one of:

"all" (default)
Use highlight.js file when given otherwise use syntect
"no-node"
Always use syntect even if a highlight.js file is given. In this case you can give .sublime-syntax files in your theme folder that will be used for highlighting. This way you can have a faster alternative to Node whilst keeping custom highlighting
"none"
Don't do any highlighting

It's worth noting that the highlighting colours for syntect and highlight.js are different because they're different programs

If you use syntect, you can provide a custom theme.tmtheme file in your theme directory. If this is a valid theme, that'll get used for highlighting. If not, the theme base16-ocean.light is used instead.

Why does it take so long?

If you're using a custom highlight.js file, this might make the renderer a bit slow. This is due to having to call Node.js for each code block. You should only use this if you require highlighting a language not supported by syntect.

Things still to add

Images (This is not possible with genpdf... at the moment)
Custom highlight.js theme application (Can have a custom syntect theme)

Dependencies

If you want to know what different dependencies are used for, here you go. The descriptions are all a bit general, because anything more specific would make the table too big.

Dependency	Version	Use
`serde`	1.0.152	Config struct deserialisation
`mdbook`	0.4.25	Getting mdbook config and some error printing
`genpdf`	0.2.0	PDF building (really nice library btw)
`anyhow`	1.0.68	Error handling
`scraper`	0.14.0	Parsing HTML outputs
`ego-tree`	0.6.2	Required for function call types when highlighting
`pulldown-cmark`	0.9.2	Markdown parsing
`syntect`	0.5.0	Built-in code highlighting

RosiePuddles/mdbook-compress