openbayes/docusaurus-prince-pdf

Docusaurus Prince PDF Generator

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

演示/示例

!Docusaurus文档的Prince PDF效果

您可以在https://github.com/signcl/docusaurus-prince-pdf/actions/workflows/test.yml%E7%9A%84%E5%88%B6%E5%93%81%E9%83%A8%E5%88%86%E4%B8%8B%E8%BD%BD%E6%9F%A5%E7%9C%8B%E7%BB%93%E6%9E%9C%E3%80%82

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

使用方法

首先安装Prince。

运行以下命令生成PDF：

bash
# 从`docs`范围内的特定站点生成PDF
npx docusaurus-prince-pdf -u https://docusaurus.io/docs

# 将生成范围更改为`/docs/cli/`
npx docusaurus-prince-pdf -u https://docusaurus.io/docs/cli

# 自定义工作（输出）目录
npx docusaurus-prince-pdf -u https://openbayes.com/docs --dest ./pdf-output

# 自定义输出文件名
npx docusaurus-prince-pdf -u https://openbayes.com/docs --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使用

• https://hub.docker.com/r/openbayes/docusaurus-prince-pdf
• https://github.com/orgs/signcl/packages/container/package/docusaurus-prince-pdf

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

bash
docker run --rm -it --init \
  -v $(pwd)/pdf:/app/pdf \
  openbayes/docusaurus-prince-pdf \
  -u https://docusaurus.io/docs/

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

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

GitHub Actions集成

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

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

    - name: 安装Prince
      run: |
        curl https://www.princexml.com/download/prince-14.2-linux-generic-x86_64.tar.gz -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 https://docusaurus.io/docs/

    - 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 https://docusaurus.io/docs/

    # ...其他步骤

开发

您需要先安装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。更多信息请参见https://github.com/***/docker-prince
• --list-only: 仅获取列表而不生成PDF
• --pdf-only: 仅生成PDF而不获取列表。确保列表已存在
• --cookie: 指定带有域部分的cookie，例如--cookie="token=123456; domain=example.com;"

工作原理

与https://github.com/kohheepeace/mr-pdf%E7%B1%BB%E4%BC%BC%EF%BC%8C%E6%AD%A4%E5%8C%85%E5%9C%A8%E7%94%9F%E6%88%90%E7%9A%84Docusaurus%E7%AB%99%E7%82%B9%E4%B8%8A%E6%9F%A5%E6%89%BE%E4%B8%8B%E4%B8%80%E9%A1%B5%E5%88%86%E9%A1%B5%E9%93%BE%E6%8E%A5%E3%80%82%E5%B0%86%E5%AE%83%E4%BB%AC%E6%94%B6%E9%9B%86%E5%88%B0%E5%88%97%E8%A1%A8%E4%B8%AD%EF%BC%8C%E7%84%B6%E5%90%8E%E5%B0%86%E5%88%97%E8%A1%A8%E4%BC%A0%E9%80%92%E7%BB%99Prince%E4%BB%A5%E7%94%9F%E6%88%90PDF%E3%80%82

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

bash
npx docusaurus-prince-pdf -u https://openbayes.com/ --selector 'nav.custom-pagination-item--next > a'

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

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

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

bash
npx docusaurus-prince-pdf -u https://fumadocs.vercel.app/docs/ui --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：https://github.com/kohheepeace/mr-pdf%EF%BC%88%E6%9C%AC%E9%A1%B9%E7%9B%AE%E6%9C%AA%E4%BD%BF%E7%94%A8%EF%BC%89

优点：

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

缺点：

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

不足：

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

使用方法：

bash
npx mr-pdf --initialDocURLs="https://openbayes.com/docs/" --paginationSelector=".pagination-nav__item--next > a" --contentSelector="article"

许可证

MIT