React/TypeScript项目如何生成PDF格式的技术文档？

方案一：使用Typedoc专用PDF插件直接生成 #

直接借助typedoc-plugin-pdf插件，让Typedoc直接输出PDF，跳过HTML转换环节，从根源解决排版混乱和批量文件处理的问题。

1. 安装插件：

npm install typedoc-plugin-pdf --save-dev

2. 在Typedoc配置文件（如typedoc.json）中添加插件配置：

{
  "plugin": ["typedoc-plugin-pdf"],
  "pdfOut": "./docs/api-documentation.pdf",
  "pdfTheme": "light" // 可选：light/dark，也可指定自定义主题路径
}

3. 运行Typedoc命令直接生成PDF：

npx typedoc

插件会自动将所有文档内容整合为单个PDF，排版适配PDF格式，无需手动处理多份HTML文件。

方案二：通过Markdown中间层转换 #

先让Typedoc生成Markdown文档，再将Markdown转为PDF，这种方式灵活性更高，便于自定义排版样式。

1. 安装Typedoc Markdown插件：

npm install typedoc-plugin-markdown --save-dev

2. 配置Typedoc生成Markdown：

{
  "plugin": ["typedoc-plugin-markdown"],
  "out": "./docs/markdown",
  "entryPoints": ["./src/index.ts"]
}

3. 运行命令生成Markdown文件：

npx typedoc

4. 用工具将Markdown转为PDF，比如md-to-pdf：
   • 安装工具：npm install md-to-pdf --save-dev
   • 批量转换并合并：

   npx md-to-pdf ./docs/markdown/**/*.md --output ./docs/api-documentation.pdf
   

   也可以用pandoc实现更复杂的样式定制，比如指定LaTeX模板或CSS样式优化排版细节。

方案三：自定义脚本批量处理HTML转PDF #

如果必须从HTML转换，可以用Puppeteer编写脚本批量抓取HTML并生成PDF，同时通过自定义样式优化排版，最后合并为单个PDF。

1. 安装依赖工具：

npm install puppeteer pdf-lib --save-dev

2. 编写Node脚本示例：

const puppeteer = require('puppeteer');
const { PDFDocument } = require('pdf-lib');
const fs = require('fs');
const path = require('path');

async function generateAndMergePDFs(htmlDir, outputPath) {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  const pdfDocs = [];

  // 遍历目标目录下所有HTML文件
  const htmlFiles = fs.readdirSync(htmlDir).filter(file => file.endsWith('.html'));
  for (const file of htmlFiles) {
    const filePath = path.join(htmlDir, file);
    await page.goto(`file://${filePath}`, { waitUntil: 'networkidle0' });
    
    // 注入自定义CSS优化PDF排版
    await page.addStyleTag({ content: `
      body { font-family: Arial, sans-serif; margin: 20px; }
      h1, h2 { page-break-after: avoid; }
      code { background: #f5f5f5; padding: 2px 4px; border-radius: 4px; }
      .tsd-navigation { display: none; } /* 可隐藏不必要的侧边栏 */
    ` });

    // 生成单份PDF文件
    const pdfBytes = await page.pdf({
      format: 'A4',
      margin: { top: '20mm', right: '15mm', bottom: '20mm', left: '15mm' }
    });
    pdfDocs.push(pdfBytes);
  }

  await browser.close();

  // 合并所有PDF文件
  const mergedPdf = await PDFDocument.create();
  for (const pdfBytes of pdfDocs) {
    const pdf = await PDFDocument.load(pdfBytes);
    const pages = await mergedPdf.copyPages(pdf, pdf.getPageIndices());
    pages.forEach(page => mergedPdf.addPage(page));
  }

  const mergedPdfBytes = await mergedPdf.save();
  fs.writeFileSync(outputPath, mergedPdfBytes);
}

// 执行脚本：传入HTML目录和输出PDF路径
generateAndMergePDFs('./docs/html', './docs/api-documentation.pdf');

3. 运行脚本：

node generate-pdf.js

该脚本可批量处理所有HTML文件，通过自定义CSS修复排版问题，最终合并为单个PDF文件。

内容的提问来源于stack exchange，提问作者wagner tanaka