diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index b24e007..c8eac4e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -17,6 +17,8 @@ jobs: runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@v2 + with: + submodules: 'recursive' - uses: Swatinem/rust-cache@v1 - name: Build mdbook-pdf Release run: | @@ -44,6 +46,8 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 + with: + submodules: 'recursive' - run: | echo '#!/bin/bash' >> script.sh echo "cd /build" >> script.sh diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 1a4cabe..04d8a09 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -136,6 +136,8 @@ jobs: runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@v2 + with: + submodules: 'recursive' - uses: Swatinem/rust-cache@v1 - name: Install mdbook related backend if: matrix.backend-depends != '' @@ -230,6 +232,8 @@ jobs: runs-on: "windows-latest" steps: - uses: actions/checkout@v2 + with: + submodules: 'recursive' - uses: Swatinem/rust-cache@v1 - name: Install mdbook related backend if: matrix.backend-depends != '' diff --git a/Cargo.toml b/Cargo.toml index bb0ce9e..4093a46 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -16,7 +16,7 @@ readme = "README.md" # headless_chrome = { git = "https://github.com/atroche/rust-headless-chrome", branch = "master", features= ["fetch"] } # A forked version to expand some response timeout to 300 seconds. -headless_chrome = { git = "https://github.com/HollowMan6/rust-headless-chrome" } +mdbook-pdf-headless_chrome = "0.1.0" mdbook = "0.4.15" -serde = "1.0.134" -serde_derive = "1.0.134" +serde = "1.0.136" +serde_derive = "1.0.136" diff --git a/README.md b/README.md index e3e0ac7..ed45654 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # mdbook-pdf [![last-commit](https://img.shields.io/github/last-commit/HollowMan6/mdbook-pdf)](https://github.com/HollowMan6/mdbook-pdf/graphs/commit-activity) +[![release-date](https://img.shields.io/github/release-date/HollowMan6/mdbook-pdf)](https://github.com/HollowMan6/mdbook-pdf/releases) +[![Crate](https://img.shields.io/crates/v/mdbook-pdf.svg)](https://crates.io/crates/mdbook-pdf) ![mdbook-pdf build](https://github.com/HollowMan6/mdbook-pdf/workflows/mdbook-pdf%20build/badge.svg) ![mdbook-pdf test](https://github.com/HollowMan6/mdbook-pdf/workflows/mdbook-pdf%20test/badge.svg) @@ -18,15 +20,17 @@ A backend for [mdBook](https://github.com/rust-lang/mdBook) written in Rust for generating PDF based on [headless chrome](https://github.com/atroche/rust-headless-chrome) and [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF). ## Usage -If your machine's architecture is `x86_64`, check the successful [build GitHub Actions workflows](https://github.com/HollowMan6/mdbook-pdf/actions/workflows/build.yml?query=is%3Asuccess), click into the latest one, and then you can get a binary from the Artifacts (including `Windows`, `Linux`, `macOS`). +If 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), click into the latest one, and then you can get a binary from the Artifacts (including `Windows`, `Linux`, `macOS`). -Otherwise, make sure the Rust build environment is available (`cargo build`). -Then run `cargo build --release` in this folder, get the executable in `target/release/`, and put it in PATH. +Otherwise, 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 --recursive 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](https://github.com/atroche/rust-headless-chrome/issues/286). - 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 old versions of Windows without Edge, you can install Google Chrome on your computer. -- In MacOS, you need to install [Google Chrome](https://www.google.com/chrome/). +- In MacOS, you need to install [Google Chrome](https://www.google.com/chrome/) / [Microsoft Edge](https://www.microsoft.com/en-us/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` or `chromium-browser` (Note: for Ubuntu later than 18.04, you have to install `chromium-browser` through `snap`). Make sure the following exists in your `book.toml`: @@ -44,12 +48,25 @@ And also `[output.html.print]` is not disabled (it should be enabled by default, enable = true ``` +A simplest `book.toml` is as follows: + +```toml +[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`. +(Note: Because I found that special characters such as `:` are very likely to appear in the title of the book, which will cause the generation of the related PDF file to fail, so the file name does not use the form of `.pdf` but `output.pdf`) + ## Configuration 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](test_doc/book.toml#L10-L33) for details for the available configurations of `[output.pdf]`. +Check [book.toml](test_doc/book.toml#L10-L33) and comments for details for the available configurations of `[output.pdf]`. -## Crates.io -This package currently won't be published to [crates.io](https://crates.io) as one of the dependencies applies patches from the [headless chrome GitHub fork](https://github.com/HollowMan6/rust-headless-chrome), and the patches [won't be merged to upstream](https://github.com/atroche/rust-headless-chrome/issues/287). +## Credits +This project relies on [headless_chrome](https://github.com/atroche/rust-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](https://github.com/HollowMan6/rust-headless-chrome) to published [mdbook-pdf-headless_chrome](https://crates.io/crates/mdbook-pdf-headless_chrome) for expanding the relevant timeout to 300 seconds as a submodule of this project, thus enabling the project to be published on [Crates.io](https://crates.io/) as well. diff --git a/README_CN.md b/README_CN.md index ef12edf..4efbc9e 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,6 +1,8 @@ # mdbook-pdf [![last-commit](https://img.shields.io/github/last-commit/HollowMan6/mdbook-pdf)](https://github.com/HollowMan6/mdbook-pdf/graphs/commit-activity) +[![release-date](https://img.shields.io/github/release-date/HollowMan6/mdbook-pdf)](https://github.com/HollowMan6/mdbook-pdf/releases) +[![Crate](https://img.shields.io/crates/v/mdbook-pdf.svg)](https://crates.io/crates/mdbook-pdf) ![mdbook-pdf build](https://github.com/HollowMan6/mdbook-pdf/workflows/mdbook-pdf%20build/badge.svg) ![mdbook-pdf test](https://github.com/HollowMan6/mdbook-pdf/workflows/mdbook-pdf%20test/badge.svg) @@ -15,19 +17,21 @@ [English](README.md) -[v0.1.0开发文档](https://openeuler.feishu.cn/docs/doccnQFaB5OLABMDjhWSE1siX5b#) +[v0.1.0 开发文档](https://openeuler.feishu.cn/docs/doccnQFaB5OLABMDjhWSE1siX5b#) 用 Rust 编写的 [mdBook](https://github.com/rust-lang/mdBook) 后端，基于[headless chrome](https://github.com/atroche/rust-headless-chrome)和[Chrome开发工具协议](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF)生成PDF。 ## 用法 -如果您的计算机的架构为`x86_64`，请检查成功的[build GitHub Actions workflows](https://github.com/HollowMan6/mdbook-pdf/actions/workflows/build.yml?query=is%3Asuccess)，单击最新的一次运行记录，然后您可以从 Artifacts中获取二进制文件（包括 `Windows`、`Linux`、`macOS`）。 +如果您的计算机的架构为`x86_64`，或者`Arm64`版本的Linux，请检查成功的[build GitHub Actions workflows](https://github.com/HollowMan6/mdbook-pdf/actions/workflows/build.yml?query=is%3Asuccess)，单击最新的一次运行记录，然后您可以从 Artifacts中获取二进制文件（包括 `Windows`、`Linux`、`macOS`）。 -否则，请确保 Rust 编译环境可用（`cargo build`），然后在此文件夹中运行`cargo build --release`，在`target/release/`中获取可执行文件，并将其放入PATH。 +否则，执行`cargo install mdbook-pdf`编译安装即可。 + +如果需要最新版的编译二进制文件，请确保 Rust 编译环境可用（`cargo build`），然后执行`git clone --recursive https://github.com/HollowMan6/mdbook-pdf.git`，在然后在克隆下来的文件夹中运行`cargo build --release`，在`target/release/`中获取可执行文件，并将其放入PATH。 为了使得程序能够正常运行，请确保计算机上安装了 Google Chrome / Chromium / Microsoft Edge，（安装在默认的位置，在当前的PATH中，或配置了二进制文件位置），因为现在自动下载 Chromium 功能还[不可用](https://github.com/atroche/rust-headless-chrome/issues/286). - 在Windows 10及以上该程序无需安装任何额外软件即可正常生成 PDF，因为 Microsoft Edge 是 Windows 系统自带的浏览器。当然如果考虑到对没有自带安装 Edge 的老版本Windows的支持，在电脑上安装一个 Google Chrome 即可。 -- 在 macOS 中需要下载并安装 [Google Chrome](https://www.google.com/chrome/)。 +- 在 macOS 中需要下载并安装 [Google Chrome](https://www.google.com/chrome/) 或者 [Microsoft Edge](https://www.microsoft.com/zh-cn/edge) 或者 Chromium。 - 在 Linux 中安装Google Chrome / Chromium / Microsoft Edge 浏览器中的任意一个即可，推荐安装 Chromium，该软件包在您的发行版中一般名称为 `chromium` 或 `chromium-browser`（注意，在 Ubuntu 18.04 之后需要通过 `snap` 安装 `chromium-browser`）。 请确保您的`book.toml`中存在以下内容: @@ -45,12 +49,105 @@ enable = true ``` +一个最简单的`book.toml`文件示例如下： + +```toml +[book] +title = "An Example" + +[output.html] + +[output.pdf] +``` + 最后，您可以使用 `mdbook build` 命令生成书籍并获取PDF文件，您的PDF文件将被存放在`book/pdf/output.put`。 +(注：因为注意到书名中很容易出现特殊字符，比如说`:`，这样的话会导致生成相关PDF文件失败，所以文件名没有使用`<书名>.pdf`这种的形式，而是统一用`output.pdf`) + ## 配置 支持自定义PDF纸张方向、页面缩放比例、纸张宽度和高度、页面边距、生成的PDF页面范围、是否显示页眉和页脚以及自定义其格式等。 查看 [book.toml](test_doc/book.toml#L10-L33) 以了解 `[output.pdf]` 可用配置的详细信息。 -## Crates.io -由于本软件的依赖使用了来自 [headless chrome GitHub fork](https://github.com/HollowMan6/rust-headless-chrome) 的补丁，并且[该补丁并不会被合并](https://github.com/atroche/rust-headless-chrome/issues/287)，因而目前不会在 [crates.io](https://crates.io) 中发布。 +### 具体参数详解 +- trying-times + +接受输入一个整型数，默认为`1`。其指定假如发生PDF生成失败的情况重试的次数。 + +- browser-binary-path + +接受输入一个字符串，默认为空`''`，程序自动判断路径。其指定浏览器可执行文件路径。 + +本程序支持最新的基于Chromium的浏览器，不支持Safari和Firefox。如果你需要指定，请指定完整的路径，比如说`/usr/bin/foo`。如果指定了错误的可执行文件，则很可能会出现超时错误或者直接报错。 + +- landscape + +接受输入一个布尔值，默认为`false`。其指定PDF纸张方向，`true`为横向，`false`为纵向。 + +- display-header-footer + +接受输入一个布尔值，默认为`false`。其指定是否显示页眉和页脚，`true`为显示，`false`为不显示。 + +- print-background + +接受输入一个布尔值，默认为`false`。其指定是否在PDF中显示背景图片，`true`为显示，`false`为不显示。 + +- scale + +接受输入一个数字，默认为`1`。其指定缩放因子，例如指定值为`1.25`，则将页面缩放125%。 + +- paper-width + +接受输入一个数字，默认为`8.5`。其指定页面宽度的英尺数，如果需要使用A4纸请将此值设为`8`。 + +- paper-height + +接受输入一个数字，默认为`11`。其指定页面高度的英尺数，如果需要使用A4纸请将此值设为`10`。 + +- margin-top + +接受输入一个数字，默认为`1`。其指定页面上边距的厘米数。 + +- margin-bottom + +接受输入一个数字，默认为`1`。其指定页面下边距的厘米数。 + +- margin-left + +接受输入一个数字，默认为`1`。其指定页面左边距的厘米数。 + +- margin-right + +接受输入一个数字，默认为`1`。其指定页面右边距的厘米数。 + +- page-range + +接受输入一个字符串，默认为空`''`，即不截取PDF页面。其指定生成PDF文件页面截取范围，支持指定常见打印机格式页面范围，如`'1-5, 8, 11-13'`则是将第1到5页以及第8页和第11到13页截取出来生成。 + +- ignore-invalid-page-ranges + +接受输入一个布尔值，默认为`false`。其指定，如果上面指定的PDF文件页面截取范围格式正确，但是实际无法按照语义执行，是否忽略。`true`为忽略，生成全部PDF页面，`false`为进行报错，如在指定`3-2`这种情况下将会报错，PDF生成失败。 + +- header-template + +接受输入一个字符串。其指定PDF文件页眉的HTML模板。其值应该是一个有效的HTML标记，并使用以下类从而将对应值插入其中： + + - date: 格式化后的PDF生成日期 + - title: 书的标题 + - url: PDF文件存放路径 + - pageNumber: 当前页号 + - totalPages: 总共页数 + +例如，`''` 将生成一个包含标题的页眉。 + +- footer-template + +接受输入一个字符串。其指定PDF文件页脚的HTML模板。其值的格式同header-template。 + +- prefer-css-page-size + +接受输入一个布尔值，默认为`false`。其指定是否使用 CSS 定义的页面大小。`true`为使用，`false`时页面将通过缩放来适应纸张大小。 + +## 致谢 + +本项目依赖于 [headless_chrome](https://github.com/atroche/rust-headless-chrome)。因其一直未发布新版，且默认超时时间对PDF生成不友好，所以使用了我的[Fork 版本](https://github.com/HollowMan6/rust-headless-chrome)发布了[mdbook-pdf-headless_chrome](https://crates.io/crates/mdbook-pdf-headless_chrome)，将相关超时时间扩大为300秒，作为本项目的子模块，从而使得项目能够发布在[Crates.io](https://crates.io/)