Docusaurus Prince PDF Generator

从Docusaurus/Fumadocs等文档站点提取渲染数据并生成PDF文件的工具

演示/示例

!Docusaurus文档的Prince PDF效果

您可以在GitHub Actions的制品部分下载查看结果。

本项目使用方法1（见下文）生成PDF。您的本地机器必须安装Prince。

使用方法

首先安装Prince。

运行以下命令生成PDF：

bash
# 从`docs`范围内的特定站点生成PDF
npx docusaurus-prince-pdf -u [***]

# 将生成范围更改为`/docs/cli/`
npx docusaurus-prince-pdf -u [***]

# 自定义工作（输出）目录
npx docusaurus-prince-pdf -u [***] --dest ./pdf-output

# 自定义输出文件名
npx docusaurus-prince-pdf -u [***] --output docs.pdf

要从本地Docusaurus实例生成PDF，您需要先在本地构建站点：

bash
# 构建站点
(npm|bun|yarn|pnpm) build

# 在本地提供构建好的站点
(npm|bun|yarn|pnpm) serve

# 从本地Docusaurus实例生成PDF
npx docusaurus-prince-pdf -u http://localhost:4000/docs # 将端口更改为您的服务端口

Docker使用

• Docker Hub
• ghcr.io

您可以使用Docker镜像运行此程序：

bash
docker run --rm -it --init \
  -v $(pwd)/pdf:/app/pdf \
  openbayes/docusaurus-prince-pdf \
  -u [***]

如果需要支持中文和日文等亚洲语言，您可以将自定义字体目录挂载到Docker镜像：

bash
docker run --rm -it --init \
  -v $(pwd)/pdf:/app/pdf \
  -v $(pwd)/fonts:/root/.fonts \
  openbayes/docusaurus-prince-pdf \
  -u [***]

GitHub Actions集成

您也可以在GitHub Actions中运行此程序：

yaml
jobs:
  build:
    # 前置条件...

    - name: 安装Prince
      run: |
        curl [***] -O
        tar zxf prince-14.2-linux-generic-x86_64.tar.gz
        cd prince-14.2-linux-generic-x86_64
        yes "" | sudo ./install.sh

    - name: 构建PDF
      run: npx docusaurus-prince-pdf -u [***]

    - name: 上传结果
      uses: actions/upload-artifact@v3
      with:
        name: result
        # 可以使用--output选项指定输出文件名
        path: pdf/docusaurus.io-docs.pdf
        if-no-files-found: error

    # ...其他步骤

您也可以使用预构建的Prince Docker镜像运行prince：

yaml
jobs:
  build:
    # 前置条件...

    - name: 构建PDF
      run: docker run --rm -it -v $(pwd)/pdf:/app/pdf openbayes/docusaurus-prince-pdf -u [***]

    # ...其他步骤

开发

您需要先安装Bun。这也可以让您在本地机器上运行最新代码。

bash
bun run index.ts -u http://localhost:4000/docs

选项

• --url (-u): 基础URL，应为Docusaurus实例的baseUrl（例如[***]
• --selector (-s): 用于查找下一页链接的CSS选择器
• --dest (-d): 工作目录。默认为./pdf
• --file (-f): 更改默认列表输出文件名
• --output (-o): 更改PDF输出文件名
• --include-index: 将传递的URL包含在生成的PDF中
• --prepend: 前置附加页面，用逗号分隔
• --append: 追加附加页面，用逗号分隔
• --prince-args: Prince的附加选项。例如--prince-args="--page-size='210mm 297mm'"或--prince-args "\\-\\-page\\-size='210mm 297mm'"
• --prince-docker: 使用外部Prince Docker镜像生成PDF。更多信息请参见[***]
• --list-only: 仅获取列表而不生成PDF
• --pdf-only: 仅生成PDF而不获取列表。确保列表已存在
• --cookie: 指定带有域部分的cookie，例如--cookie="token=***; domain=example.com;"

工作原理

与mr-pdf类似，此包在生成的Docusaurus站点上查找下一页分页链接。将它们收集到列表中，然后将列表传递给Prince以生成PDF。

如果您使用自定义Docusaurus主题，可以指定CSS选择器：

bash
npx docusaurus-prince-pdf -u [***] --selector 'nav.custom-pagination-item--next > a'

是否适用于Fumadocs或其他静态站点/文档生成器？

它应该适用于任何具有一致分页链接的静态站点/文档生成器。

对于Fumadocs，您可以使用相同的方法通过自定义选择器生成PDF：

bash
npx docusaurus-prince-pdf -u [***] --selector '#nd-page > article > div.grid.grid-cols-2.gap-4.pb-6 a:last-child'

Tailwind样式的选择器不够优雅，但可以工作。

为什么选择此工具？

我对从Docusaurus生成PDF的两种方法进行了比较。

方法1：Prince

优点：

• 最佳字体子集支持
• 文本可以正确选择和复制粘贴
• 精美的目录

缺点：

• 生成的PDF第一页上的水印使得在CI/CD环境中难以处理
• 不适用于某些CSS语法（例如mask-image）
• 不适用于某些HTML功能（例如srcset）
• 商业许可证价格昂贵（$3,800）

不足：

• 无

方法2：mr-pdf（本项目未使用）

优点：

• 免费开源
• 适用于Docusaurus站点
• CI/CD友好
• 基于Puppeteer，适用于大多数现代CSS语法（例如mask-image）

缺点：

• 在系统深色模式下表现不佳。当您在Docusaurus实例中启用respectPrefersColorScheme时，生成的PDF会有深色背景。但在CI/CD环境中不是问题
• 没有目录

不足：

• 基于Puppeteer导致文本无法正确复制或搜索
• 链接锚点（以#开头的链接）处理不当

使用方法：

bash
npx mr-pdf --initialDocURLs="[***]" --paginationSelector=".pagination-nav__item--next > a" --contentSelector="article"

许可证

MIT