Package: mdbook-pdf-outline
mdbook-pdf中文BlogA backend formdBookwritten in Rust for generating PDF based onheadless chromeandChrome DevTools Protocol.Installation & UsageSince it's a plugin (backend) formdBook, first of all you should ensure thatmdbookis available.If your machine's architecture isx86_64, or you are using Linux forARM64, check the successfulbuild GitHub Actions workflows/release, click into the latest one, and then you can get a binary from the Artifacts (includingWindows,Linux,macOS).Otherwise, make sure therust compiling environmentis available, executecargo install mdbook-pdfto compile and install.If you want to compile the latest version, make sure the Rust build environment is available (cargo build).
Then rungit clone https://github.com/HollowMan6/mdbook-pdf.git, in the cloned folder, runcargo build --release, get the executable intarget/release/, and put it in PATH.For running, please have Google Chrome / Chromium / Microsoft Edge already available (installed at the default location, in PATH or binary location configured). If not, andmdbook-pdfhas thefetchfeature enabled (It is not enabled by default, you need to usecargo install mdbook-pdf --features fetchto recompile for enabling), the program will try to automatically download the Chromium browser and run it (Note: if you are on Linux, there may be problems if chromium dependencies are not satisfied / using non-x86_64 architectures).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 installGoogle Chrome/Microsoft Edgeor 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 commonlychromiumorchromium-browser(Note: for Ubuntu later than 18.04, you have to installchromium-browserthroughsnap).Make sure the following exists in yourbook.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 youbook.toml).[output.html.print]enable=trueA simplestbook.tomlis as follows:[book]title="An Example"[output.html][output.pdf]Finally you can build your book and get the PDF file withmdbook buildcommand, your PDF file will be available atbook/pdf/output.pdf.Run with DockerYou can also use thisdocker image.dockerrun--rm-v/path/to/book:/bookhollowman6/mdbook-pdfIf your book have other Rust dependencies, you can install them on your local machine (if using Linux), or if you are not using Linux, download the Linux executables of corresponding architecture to a dir, replace~/.cargo/binwith your path.dockerrun--rm-v/path/to/book:/book-v~/.cargo/bin:/mdbookhollowman6/mdbook-pdfConfigurationSupport 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.Checkbook.tomland comments for details for the available configurations of[output.pdf].Common IssuesSupport for Firefox inmdbook-pdf!Currently, according toPuppeteer's documentation,Chrome DevTools Protocol Page.printToPDFis only supported in Chrome headless. An issue has already been filed for thishere.Broken links!I've already submitteda PR for mdBookto fix this by making print page (print.html) links link to anchors on the print page, but it's not merged yet. You can trymy PR forkfor this to work.If you have relative links that link outside the book, please provide thestatic hosting site URLfor it to get fixed.Can you add the bookmark to the PDF reflecting the Table of Contents, just like whatwkhtmltopdfsupported?This should be realized by Chromium, and an issue has already been filed for thishere.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 formdbookand should be used withmdbook-pdfandthemdbook versionmentioned in Common Issues 2 (bycargo install --git https://github.com/HollowMan6/mdBook mdbookinstead) for fixing the broken links inprint.html.You can install this backend bypip install mdbook-pdf-outline.Remember to put the following tothe end ofyourbook.toml,after [output.pdf]:[output.pdf-outline]If you want to use the table of content just like the one shown in theprint.htmlpage for PDF file, you can leave thebook.tomlas it is.If you prefer to use the table of content just like the one generated bywkhtmltopdf(generate entries based on the headings), you can turn on thelike-wkhtmltopdfoption by using the following to yourbook.toml:[output.pdf-outline]like-wkhtmltopdf=trueFinally, you can find the outlined version atbook/pdf-outline/output.pdf.Failed to render my book for PDF inmdbook-pdf!Will appreciate if you can report it to theissue trackerproviding all the traces formdbook-pdfrendering as well as yourbook.toml. You can also provide the link to your book's repository if it's open source.RUST_BACKTRACE=fullRUST_LOG=tracemdbookbuildCreditsThis project relies onheadless_chrome. Because the default timeout is not friendly to PDF generation, I use myforked versionto publishedmdbook-pdf-headless_chromefor expanding the relevant timeout to 600 seconds, thus enabling the project to be published onCrates.ioas well.