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).
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.
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]
subtitle = ""
font.regular = "" font.bold = "" font.italic = "" font.bold-italic = "" font.monospace = ""
fontsize.title = 12 fontsize.h1 = 11 font_size.h2 = 10
fontsize.h3 = 8 fontsize.h4 = 7 fontsize.h5 = 6 fontsize.h6 = 6 font_size.text = 5
page.size = "A4" page.landscape = false
page.new_pages = false
page.spacing.line = 1.5 page.spacing.heading = 2.0 page.spacing.margin = [20.0, 20.0]
highlight = "all" ```
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" }
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.
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.
genpdf... at the moment)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 |