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 or don't have Node.js installed, you can specify you don't want highlighting in the config settings with highlight = false.

Usage

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

toml [output.compress]

and install this project

bash 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 reaoson 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.

```toml [output.compress]

You can optionally specify a subtitle. If you don't the PDF

won't include a subtitle

subtitle = ""

Font sizes. Any heading after H6 will use the H6 font size

All font sizes will become a u8

fontsize.title = 12 fontsize.h1 = 11 font_size.h2 = 10

H3 is also used for the subtitle

fontsize.h3 = 8 fontsize.h4 = 7 fontsize.h5 = 6 fontsize.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

Line and margin spacing. Both measured in millimeters (f64 internally)

page.spacing.line = 1.5 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 toml 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 - "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

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
• Better padding support for blocks
• Custom highlight.js theme application

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 |