A backend for mdBook written in Rust for generating PDF based on headless chrome and Chrome DevTools Protocol.
Since it's a plugin (backend) for mdBook, first of all you should ensure that mdbook
is available.
If your machine's architecture is x86_64
, or you are using Linux for ARM64
, check the successful build GitHub Actions workflows/release, click into the latest one, and then you can get a binary from the Artifacts (including Windows
, Linux
, macOS
).
Otherwise, make sure the rust compiling environment is available, execute cargo install mdbook-pdf
to compile and install.
If you want to compile the latest version, make sure the Rust build environment is available (cargo build
).
Then run git clone https://github.com/HollowMan6/mdbook-pdf.git
, in the cloned folder, run cargo build --release
, get the executable in target/release/
, and put it in PATH.
For running, have Google Chrome / Chromium / Microsoft Edge available (installed at the default location, in PATH or binary location configured) as currently, automatically downloading Chromium binary isn't available (will update once upstream fixes such support).
- On Windows 10 and above, the program can generate PDF normally without installing any additional software, because Microsoft Edge is the browser provided with Windows system. Of course, considering the support for the older versions of Windows without Edge, you can install Google Chrome on your computer.
- In MacOS, you need to install Google Chrome / Microsoft Edge or Chromium.
- In Linux, you can choose to install any of the Google Chrome / Chromium / Microsoft Edge browsers. It is recommended to install Chromium. The name of this software package in your Linux distribution is commonly
chromium
orchromium-browser
(Note: for Ubuntu later than 18.04, you have to installchromium-browser
throughsnap
).
Make sure the following exists in your book.toml
:
[output.html]
[output.pdf]
And also [output.html.print]
is not disabled (it should be enabled by default, so don't worry if the following lines doesn't occur in you book.toml
).
[output.html.print]
enable = true
A simplest book.toml
is as follows:
[book]
title = "An Example"
[output.html]
[output.pdf]
Finally you can build your book and get the PDF file with mdbook build
command, your PDF file will be available at book/pdf/output.pdf
.
Support customize PDF paper orientation, scale of the webpage rendering, paper width and height, page margins, generated PDF page ranges, whether to display header and footer as well as customize their formats, and more.
Check book.toml and comments for details for the available configurations of [output.pdf]
.
- Support for Firefox in
mdbook-pdf
!
Currently, according to Puppeteer's documentation, Chrome DevTools Protocol Page.printToPDF is only supported in Chrome headless. An issue has already been filed for this here.
- Broken links!
I've already submitted a PR for mdBook to fix this by making print page (print.html) links link to anchors on the print page, but it's not merged yet. You can try my PR fork for this to work.
If you have relative links that link outside the book, please provide the static hosting site URL for it to get fixed.
- Can you add the bookmark to the PDF reflecting the Table of Contents, just like what wkhtmltopdf supported?
This should be realized by Chromium, and an issue has already been filed for this here.
Initial support for the bookmark/outline of the PDF file has already been available (mdbook-pdf-outline). It is written in Python and is another backend for mdbook
and should be used with mdbook-pdf
and the mdbook version mentioned in Common Issues 2 for fixing the broken links in print.html
.
You can install this backend by pip install mdbook-pdf-outline
.
Remember to put the following to the end of your book.toml
, after [output.pdf]:
[output.pdf-outline]
If you want to use the table of content just like the one shown in the print.html
page for PDF file, you can leave the book.toml
as it is.
If you prefer to use the table of content just like the one generated by wkhtmltopdf
(generate entries based on the headings), you can turn on the like-wkhtmltopdf
option by using the following to your book.toml
:
[output.pdf-outline]
like-wkhtmltopdf = true
Finally, you can find the outlined version at book/pdf-outline/output.pdf
.
- Failed to render my book for PDF in
mdbook-pdf
!
Will appreciate if you can report it to the issue tracker providing all the traces for mdbook-pdf
rendering.
RUST_BACKTRACE=full RUST_LOG=trace mdbook build
This project relies on headless_chrome. Because the new version has not been released, and the default timeout is not friendly to PDF generation, I use my Fork version to published mdbook-pdf-headless_chrome for expanding the relevant timeout to 600 seconds as a submodule of this project, thus enabling the project to be published on Crates.io as well.