{"id":13689536,"url":"https://github.com/HollowMan6/mdbook-pdf","last_synced_at":"2025-05-02T00:30:31.321Z","repository":{"id":41555126,"uuid":"449251644","full_name":"HollowMan6/mdbook-pdf","owner":"HollowMan6","description":"A backend for mdBook written in Rust for generating PDF based on headless chrome and Chrome DevTools Protocol. (用 Rust 编写的 mdBook 后端，基于headless chrome和Chrome开发工具协议生成PDF)","archived":false,"fork":false,"pushed_at":"2025-03-09T20:56:44.000Z","size":159,"stargazers_count":173,"open_issues_count":1,"forks_count":18,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-19T04:13:42.147Z","etag":null,"topics":["book","chromium","hacktoberfest","mdbook","pdf","rust","rust-lang"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/mdbook-pdf","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HollowMan6.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"HollowMan6","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"custom":"https://hollowman6.github.io/fund.html"}},"created_at":"2022-01-18T11:09:43.000Z","updated_at":"2025-04-11T09:23:00.000Z","dependencies_parsed_at":"2023-12-05T09:30:53.476Z","dependency_job_id":"5dbda90c-b860-4cbc-8ae4-72d834ae3a54","html_url":"https://github.com/HollowMan6/mdbook-pdf","commit_stats":{"total_commits":23,"total_committers":1,"mean_commits":23.0,"dds":0.0,"last_synced_commit":"1c4e81cc0e84d704555fd09eec0e75899937a69e"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HollowMan6%2Fmdbook-pdf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HollowMan6%2Fmdbook-pdf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HollowMan6%2Fmdbook-pdf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HollowMan6%2Fmdbook-pdf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HollowMan6","download_url":"https://codeload.github.com/HollowMan6/mdbook-pdf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251966431,"owners_count":21672666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["book","chromium","hacktoberfest","mdbook","pdf","rust","rust-lang"],"created_at":"2024-08-02T15:01:51.537Z","updated_at":"2025-05-02T00:30:31.313Z","avatar_url":"https://github.com/HollowMan6.png","language":"Rust","funding_links":["https://github.com/sponsors/HollowMan6","https://hollowman6.github.io/fund.html"],"categories":["hacktoberfest","Rust"],"sub_categories":[],"readme":"# mdbook-pdf\n[![](https://dockeri.co/image/hollowman6/mdbook-pdf)](https://hub.docker.com/r/hollowman6/mdbook-pdf)\n\n[![last-commit](https://img.shields.io/github/last-commit/HollowMan6/mdbook-pdf)](https://github.com/HollowMan6/mdbook-pdf/graphs/commit-activity)\n[![release-date](https://img.shields.io/github/release-date/HollowMan6/mdbook-pdf)](https://github.com/HollowMan6/mdbook-pdf/releases)\n[![Crate](https://img.shields.io/crates/v/mdbook-pdf.svg)](https://crates.io/crates/mdbook-pdf)\n![mdbook-pdf build](https://github.com/HollowMan6/mdbook-pdf/workflows/mdbook-pdf%20build/badge.svg)\n![mdbook-pdf test](https://github.com/HollowMan6/mdbook-pdf/workflows/mdbook-pdf%20test/badge.svg)\n![Python package](https://github.com/HollowMan6/mdbook-pdf/workflows/Python%20package/badge.svg)\n\n[![Followers](https://img.shields.io/github/followers/HollowMan6?style=social)](https://github.com/HollowMan6?tab=followers)\n[![watchers](https://img.shields.io/github/watchers/HollowMan6/mdbook-pdf?style=social)](https://github.com/HollowMan6/mdbook-pdf/watchers)\n[![stars](https://img.shields.io/github/stars/HollowMan6/mdbook-pdf?style=social)](https://github.com/HollowMan6/mdbook-pdf/stargazers)\n[![forks](https://img.shields.io/github/forks/HollowMan6/mdbook-pdf?style=social)](https://github.com/HollowMan6/mdbook-pdf/network/members)\n\n[![Open Source Love](https://img.shields.io/badge/-%E2%9D%A4%20Open%20Source-Green?style=flat-square\u0026logo=Github\u0026logoColor=white\u0026link=https://hollowman6.github.io/fund.html)](https://hollowman6.github.io/fund.html)\n[![GPL Licence](https://img.shields.io/badge/license-GPL-blue)](https://opensource.org/licenses/GPL-3.0/)\n[![Repo-Size](https://img.shields.io/github/repo-size/HollowMan6/mdbook-pdf.svg)](https://github.com/HollowMan6/mdbook-pdf/archive/master.zip)\n\n[中文](https://github.com/HollowMan6/mdbook-pdf/blob/main/README_CN.md)\n\n[Blog](https://hollowmansblog.wordpress.com/2022/01/30/mdbook-pdf-a-mdbook-backend-for-generating-pdf-files/)\n\nA backend for [mdBook](https://github.com/rust-lang/mdBook) written in Rust for generating PDF based on [headless chrome](https://github.com/rust-headless-chrome/rust-headless-chrome) and [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF).\n\n## Installation \u0026 Usage\nSince it's a plugin (backend) for [mdBook](https://github.com/rust-lang/mdBook), first of all you should ensure that `mdbook` is available.\n\nIf your machine's architecture is `x86_64`, or you are using Linux for `ARM64`, check the successful [build GitHub Actions workflows](https://github.com/HollowMan6/mdbook-pdf/actions/workflows/build.yml?query=is%3Asuccess)/[release](https://github.com/HollowMan6/mdbook-pdf/releases), click into the latest one, and then you can get a binary from the Artifacts (including `Windows`, `Linux`, `macOS`).\n\nOtherwise, make sure the [rust compiling environment](https://www.rust-lang.org/tools/install) is available, execute `cargo install mdbook-pdf` to compile and install.\n\nIf you want to compile the latest version, make sure the Rust build environment is available (`cargo build`). Run `cargo install --git https://github.com/HollowMan6/mdbook-pdf.git`, or alternatively, you can clone the repository and compile it yourself. (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)\n\nFor running, please have Google Chrome / Chromium / Microsoft Edge already available (installed at the default location, in PATH or binary location configured). If not, and `mdbook-pdf` has the `fetch` feature enabled (It is not enabled by default, you need to use `cargo install mdbook-pdf --features fetch` to 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).\n\n- 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.\n- In MacOS, you need to install [Google Chrome](https://www.google.com/chrome/) / [Microsoft Edge](https://www.microsoft.com/en-us/edge) or Chromium.\n- 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` or `chromium-browser` (Note: for Ubuntu later than 18.04, you have to install `chromium-browser` through `snap`).\n\nMake sure the following exists in your `book.toml`:\n\n```toml\n[output.html]\n\n[output.pdf]\n```\n\nAnd 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`).\n\n```toml\n[output.html.print]\nenable = true\n```\n\nA simplest `book.toml` is as follows:\n\n```toml\n[book]\ntitle = \"An Example\"\n\n[output.html]\n\n[output.pdf]\n```\n\nFinally 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`.\n\n## Run with Docker\nYou can also use this [docker image](https://hub.docker.com/r/hollowman6/mdbook-pdf).\n\n```bash\ndocker run --rm -v /path/to/book:/book hollowman6/mdbook-pdf\n```\n\nIf 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/bin` with your path.\n\n```bash\ndocker run --rm -v /path/to/book:/book -v ~/.cargo/bin:/mdbook hollowman6/mdbook-pdf\n```\n\n## Configuration\nSupport 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.\n\nCheck [book.toml](https://github.com/HollowMan6/mdbook-pdf/blob/main/test_doc/book.toml#L10-L39) and comments for details for the available configurations of `[output.pdf]`.\n\n## Common Issues\n1. Support for Firefox in `mdbook-pdf`!\n\nCurrently, although Puppeteer supports something similar to [Chrome DevTools Protocol Page.printToPDF](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF) according to its [documentation](https://pptr.dev/api/puppeteer.page.pdf), [rust-headless-chrome](https://github.com/rust-headless-chrome/rust-headless-chrome) doesn't.\n\n2. Broken links!\n\nI've already submitted [a PR for mdBook](https://github.com/rust-lang/mdBook/pull/1738) 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](https://github.com/HollowMan6/mdBook) for this to work.\n\nIf you have relative links that link outside the book, please provide the [static hosting site URL](https://github.com/HollowMan6/mdbook-pdf/blob/main/test_doc/book.toml#L19-L20) for it to get fixed.\n\n3. ~~Can you add the bookmark to the PDF reflecting the Table of Contents, just like what [wkhtmltopdf](https://wkhtmltopdf.org/) is supported?~~\n\nThis has already been realized by Chromium, in `v0.1.11+`, you can control it by the `generate-document-outline` option.\n\n\u003e [!NOTE]\n\u003e If you dislike the Chromium generated Table of Contents, we also have support for the bookmark/outline of the PDF file ([mdbook-pdf-outline](https://pypi.org/project/mdbook-pdf-outline/)). It is written in Python and is another backend for `mdbook` and should be used with `mdbook-pdf` and ***the [modified mdbook](https://github.com/rust-lang/mdBook/pull/1738) mentioned in Common Issues 2 (by `cargo install --git https://github.com/HollowMan6/mdBook mdbook` instead) for fixing the broken links in `print.html`***.\n\u003e \n\u003e You can install this backend by `pip install mdbook-pdf-outline`.\n\u003e \n\u003e Remember to put the following to ***the end of*** your `book.toml`, ***after [output.pdf]***, and disable the `generate-document-outline` option:\n\u003e \n\u003e ```toml\n\u003e generate-document-outline = false\n\u003e \n\u003e [output.pdf-outline]\n\u003e ```\n\u003e \n\u003e 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.\n\u003e \n\u003e 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`:\n\u003e \n\u003e ```toml\n\u003e generate-document-outline = false\n\u003e \n\u003e [output.pdf-outline]\n\u003e like-wkhtmltopdf = true\n\u003e ```\n\u003e \n\u003e Finally, you can find the outlined version at `book/pdf-outline/output.pdf`.\n\n4. Force page breaks in the markdown source that is respected by mdbook-pdf!\n\nReferring to [#9](https://github.com/HollowMan6/mdbook-pdf/discussions/9#discussioncomment-4895678), you can use the following syntax to force page breaks in the markdown source:\n\n```markdown\n\u003cdiv style=\"page-break-before:always\"\u003e\u0026nbsp;\u003c/div\u003e\n\u003cp\u003e\u003c/p\u003e\n```\n\n5. Failed to render my book for PDF in `mdbook-pdf`!\n\nWill appreciate if you can report it to the [issue tracker](https://github.com/HollowMan6/mdbook-pdf/issues/new) providing all the traces for `mdbook-pdf` rendering as well as your `book.toml`. You can also provide the link to your book's repository if it's open source.\n\n```bash\nRUST_BACKTRACE=full RUST_LOG=trace mdbook build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHollowMan6%2Fmdbook-pdf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHollowMan6%2Fmdbook-pdf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHollowMan6%2Fmdbook-pdf/lists"}