rspress-plugin-pdf-generator

为 Rspress 文档站生成 PDF。

功能

• 支持生成单个合并 PDF，或按页面拆分输出 PDF。
• 生成全站目录页。
• 合并 PDF 内部支持可点击跳转，包括页面目录跳转。
• 使用页面标题和标题层级生成 PDF document outline。
• 支持多语言输出、指定语言输出、以及多语言合并输出。

安装

pnpm add rspress-plugin-pdf-generator

插件依赖 Playwright 渲染 PDF。如果本机还没有 Chromium，可以执行：

pnpm exec playwright install chromium

使用

import * as path from 'node:path'
import { defineConfig } from '@rspress/core'
import pdfGenerator from 'rspress-plugin-pdf-generator'

export default defineConfig({
  root: path.join(__dirname, 'docs'),
  title: 'My Docs',
  logo: 'https://example.com/logo.svg',
  plugins: [
    pdfGenerator({
      mode: 'single',
      outputDir: 'pdf',
      fileName: 'site.pdf',
    }),
  ],
})

执行 rspress build 后，PDF 默认会输出到：

• single 模式下默认输出到 doc_build/pdf/en-site.pdf
• multiple 模式下输出到 doc_build/pdf/<language>/...

配置项

mode

• 类型：'single' | 'multiple'
• 默认值：'single'

控制输出一个合并 PDF，还是每个页面单独输出一个 PDF。

outputDir

• 类型：string
• 默认值：'pdf'

PDF 输出目录，默认相对于 config.outDir，也支持绝对路径。

fileName

• 类型：string
• 默认值：'site.pdf'

在 single 模式下作为合并 PDF 的文件名。

i18n

• 类型：

{
  enabled?: boolean
  languages?: string[]
  merge?: boolean
}

用于控制多语言 PDF 输出：

• enabled：开启多语言处理
• languages：只输出指定语言
• merge：在 single 模式下将选中的语言合并成一个 PDF

说明

• 插件基于构建后的 HTML 生成 PDF，因此只会在 rspress build 阶段运行。
• 页面顺序优先使用解析后的 nav -> sidebar 结构，剩余页面再按路由补齐。
• 站点 logo 读取的是 Rspress 顶层 UserConfig.logo。
• 如果你遇到 Chromium 相关问题，请先确认 Playwright 依赖已经正确安装，并且当前环境能够正常启动浏览器。必要时也可以在 src/pdf-utils.ts 中调整 PDF 渲染参数。