HTML转PDF转换器 - 支持RTL语言和像素级精确渲染的Puppeteer工具

html-to-pdf by aviz85/claude-skills-library

572 周安装量

21 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/aviz85/claude-skills-library --skill html-to-pdf

Node.js 开发自动化

🇨🇳中文介绍

HTML 转 PDF 转换器

首次使用？ 如果上方显示 setup_complete: false，请先运行 ./SETUP.md，然后将 setup_complete 设置为 true。

使用 Puppeteer（无头 Chrome）实现像素级精确的 HTML 转 PDF 转换。通过自动方向检测，为希伯来语、阿拉伯语和其他从右至左（RTL）语言提供出色的支持。

为什么选择 Puppeteer？

像素级精确渲染：使用真实的 Chrome 引擎
完整的 CSS3/HTML5 支持：Flexbox、Grid、自定义字体、背景
JavaScript 执行：渲染动态内容
自动 RTL 检测：检测希伯来语/阿拉伯语并设置方向
网络字体支持：正确加载自定义字体

关键：将内容适配到单页

html 或 body 上的背景会导致额外页面！ 请将背景放在容器元素上：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

设置（一次性）

首次使用前，请安装依赖项：

cd ~/.claude/skills/html-to-pdf && npm install

转换本地 HTML 文件：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js input.html output.pdf

将 URL 转换为 PDF：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js https://example.com page.pdf

强制 RTL 的希伯来语文档：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js hebrew.html hebrew.pdf --rtl

通过管道传递 HTML 内容：

echo "<h1>שלום עולם</h1>" | node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js - output.pdf --rtl

选项	描述	默认值
`--format=<format>`	页面格式：A4, Letter, Legal, A3, A5	A4
`--landscape`	使用横向方向	false
`--margin=<value>`	设置所有边距（例如："20mm", "1in"）	20mm
`--margin-top=<value>`	上边距	20mm
`--margin-right=<value>`	右边距	20mm
`--margin-bottom=<value>`	下边距	20mm
`--margin-left=<value>`	左边距	20mm
`--scale=<number>`	缩放因子 0.1-2.0	1
`--background`	打印背景图形	true
`--no-background`	不打印背景	-
`--header=<html>`	页眉 HTML 模板	-
`--footer=<html>`	页脚 HTML 模板	-
`--wait=<ms>`	字体/JS 的等待时间	1000
`--rtl`	强制 RTL 方向	自动检测

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js report.html report.pdf

Letter 格式，自定义边距：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js doc.html doc.pdf --format=Letter --margin=1in

希伯来语发票：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js invoice-he.html invoice.pdf --rtl

横向演示文稿：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js slides.html slides.pdf --landscape --format=A4

无边距（全出血）：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js poster.html poster.pdf --margin=0

希伯来语/RTL 最佳实践

为了在您的 HTML 中获得最佳的希伯来语渲染效果：

设置 lang 属性：<html lang="he" dir="rtl">
使用 UTF-8：<meta charset="UTF-8">
CSS 方向：向 body 添加 direction: rtl; text-align: right;
字体：使用支持希伯来语的网络字体（Noto Sans Hebrew, Heebo, Assistant）

希伯来语 HTML 结构示例（单页）：

<!DOCTYPE html>
<html lang="he" dir="rtl">
<head>
  <meta charset="UTF-8">
  <link href="https://fonts.googleapis.com/css2?family=Heebo:wght@400;700&display=swap" rel="stylesheet">
  <style>
    @page { size: A4; margin: 0; }
    html, body {
      width: 210mm;
      height: 297mm;
      margin: 0;
      padding: 0;
      overflow: hidden;
    }
    .container {
      width: 100%;
      height: 100%;
      padding: 20mm;
      box-sizing: border-box;
      font-family: 'Heebo', sans-serif;
      direction: rtl;
      text-align: right;
      background: #f5f5f5; /* 背景在容器上，而不是 body */
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>שלום עולם</h1>
    <p>זהו מסמך בעברית</p>
  </div>
</body>
</html>

字体渲染不正确

添加 --wait=2000 以增加字体加载时间
确保字体通过 @font-face 或 Google Fonts 加载

希伯来语显示为从左到右

使用 --rtl 标志强制 RTL 方向
在您的 HTML 元素中添加 dir="rtl"

分页符不起作用

使用 CSS 分页属性：

.page-break { page-break-after: always; }
.no-break { page-break-inside: avoid; }

确保设置了 --background（默认为 true）
仅在需要排除背景时使用 --no-background

自动适配内容（强制验证）

关键 - Claude 必须在每次生成 PDF 后执行此操作：

使用 Read 工具读取 PDF 文件，进行视觉检查
检查垂直溢出（空白页、内容溢出到下一页）
检查水平溢出（文本在边缘被截断）
如果发现任何问题 → 修复并重新生成（最多尝试 5 次）
仅在验证通过后向用户交付 PDF

这不是可选的。切勿在未经视觉验证的情况下交付 PDF。

需要查找的问题

问题	症状	修复方法
垂直溢出	页面底部有空白，内容在下一页	减小 `--scale`
水平截断	文本在左/右边缘被截断	减小 `--margin` 并修复 HTML 宽度
两个问题都有	内容被截断且有多余页面	先修复 HTML CSS，然后调整缩放比例

修复策略（最多 5 次尝试）

尝试 1： 默认设置

node scripts/html-to-pdf.js input.html output.pdf

尝试 2： 如果垂直溢出 → 减小缩放比例

node scripts/html-to-pdf.js input.html output.pdf --scale=0.9

尝试 3： 如果水平截断 → 减小边距

node scripts/html-to-pdf.js input.html output.pdf --scale=0.9 --margin=10mm

尝试 4： 如果仍有问题 → 更小的缩放比例 + 边距

node scripts/html-to-pdf.js input.html output.pdf --scale=0.8 --margin=5mm

尝试 5： 如果仍然失败 → 修复 HTML CSS：

/* 添加到 HTML 以防止水平溢出 */
.container {
  width: 100%;
  max-width: 100%;
  overflow-wrap: break-word;
  word-wrap: break-word;
  box-sizing: border-box;
}

5 次尝试后停止 - 使用适当的约束重新生成 HTML。

HTML 宽度修复（水平适配必需）

如果内容在边缘被截断，HTML 必须包含：

html, body {
  width: 210mm;  /* A4 宽度 */
  margin: 0;
  padding: 0;
  overflow: hidden;
}

.container {
  width: 100%;
  max-width: 100%;
  padding: 15mm;
  box-sizing: border-box;
  overflow-wrap: break-word;
}

每次生成 PDF 后，请验证：

所有文本可见（未在边缘被截断）
没有不必要的空白页
内容正确填充页面
各部分之间没有大的间隙

如果任何检查失败 → 调整并重新生成（最多 5 次）。

使用 Puppeteer 和无头 Chrome 进行渲染
等待 networkidle0 以确保所有资源加载完毕
自动等待 document.fonts.ready
支持 @page CSS 规则进行打印样式设置
设备缩放因子设置为 2 以实现清晰渲染

🇺🇸English

HTML to PDF Converter

First time? If setup_complete: false above, run ./SETUP.md first, then set setup_complete: true.

Pixel-perfect HTML to PDF conversion using Puppeteer (Chrome headless). Provides excellent support for Hebrew, Arabic, and other RTL languages with automatic direction detection.

Why Puppeteer?

Pixel-perfect rendering : Uses actual Chrome engine
Full CSS3/HTML5 support : Flexbox, Grid, custom fonts, backgrounds
JavaScript execution : Renders dynamic content
Automatic RTL detection : Detects Hebrew/Arabic and sets direction
Web font support : Loads custom fonts properly

CRITICAL: Fit Content to Single Page

Backgrounds onhtml or body cause extra pages! Put backgrounds on a container element instead:

@page { size: A4; margin: 0; }

html, body {
  width: 210mm;
  height: 297mm;
  margin: 0;
  padding: 0;
  overflow: hidden;
  /* NO background here! */
}

.container {
  width: 100%;
  height: 100%;
  padding: 20mm;
  box-sizing: border-box;
  background: linear-gradient(...); /* Background goes HERE */
}

Common causes of extra pages:

Background on html/body - always put on .container instead
Content overflow - use overflow: hidden
Margins/padding pushing content out

Tips:

Use --scale=0.75 --margin=0 if content still overflows
For landscape: use --landscape

Setup (One-time)

Before first use, install dependencies:

cd ~/.claude/skills/html-to-pdf && npm install

Quick Usage

Convert local HTML file:

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js input.html output.pdf

Convert URL to PDF:

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js https://example.com page.pdf

Hebrew document with forced RTL:

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js hebrew.html hebrew.pdf --rtl

Pipe HTML content:

echo "<h1>שלום עולם</h1>" | node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js - output.pdf --rtl

Options Reference

Option	Description	Default
`--format=<format>`	Page format: A4, Letter, Legal, A3, A5	A4
`--landscape`	Use landscape orientation	false
`--margin=<value>`	Set all margins (e.g., "20mm", "1in")	20mm
`--margin-top=<value>`	Top margin	20mm
`--margin-right=<value>`	Right margin

Examples

Basic conversion:

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js report.html report.pdf

Letter format with custom margins:

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js doc.html doc.pdf --format=Letter --margin=1in

Hebrew invoice:

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js invoice-he.html invoice.pdf --rtl

Landscape presentation:

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js slides.html slides.pdf --landscape --format=A4

No margins (full bleed):

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js poster.html poster.pdf --margin=0

Hebrew/RTL Best Practices

For best Hebrew rendering in your HTML:

Set lang attribute : <html lang="he" dir="rtl">
Use UTF-8 : <meta charset="UTF-8">
CSS direction : Add direction: rtl; text-align: right; to body
Fonts : Use web fonts that support Hebrew (Noto Sans Hebrew, Heebo, Assistant)

Example Hebrew HTML structure (single-page):

<!DOCTYPE html>
<html lang="he" dir="rtl">
<head>
  <meta charset="UTF-8">
  <link href="https://fonts.googleapis.com/css2?family=Heebo:wght@400;700&display=swap" rel="stylesheet">
  <style>
    @page { size: A4; margin: 0; }
    html, body {
      width: 210mm;
      height: 297mm;
      margin: 0;
      padding: 0;
      overflow: hidden;
    }
    .container {
      width: 100%;
      height: 100%;
      padding: 20mm;
      box-sizing: border-box;
      font-family: 'Heebo', sans-serif;
      direction: rtl;
      text-align: right;
      background: #f5f5f5; /* Background on container, NOT body */
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>שלום עולם</h1>
    <p>זהו מסמך בעברית</p>
  </div>
</body>
</html>

Troubleshooting

Fonts not rendering correctly

Add --wait=2000 for more font loading time
Ensure fonts are loaded via @font-face or Google Fonts

Hebrew appearing left-to-right

Use --rtl flag to force RTL direction
Add dir="rtl" to your HTML element

Page breaks not working

Use CSS page-break properties:

.page-break { page-break-after: always; }
.no-break { page-break-inside: avoid; }

Backgrounds not showing

Ensure --background is set (default is true)
Use --no-background only if you want to exclude backgrounds

Auto-Fit Content (MANDATORY VERIFICATION)

CRITICAL - Claude MUST do this after EVERY PDF generation:

Read the PDF file using the Read tool to visually inspect it
Check for vertical overflow (empty pages, content spilling to next page)
Check for horizontal overflow (text cut off at sides)
If ANY issue found → FIX and regenerate (max 5 attempts)
Only deliver PDF to user after verification passes

This is NOT optional. Never deliver a PDF without visual verification.

Problems to Look For

Problem	Symptom	Fix
Vertical overflow	Empty space at page bottom, content on next page	Reduce `--scale`
Horizontal cut-off	Text cut at left/right edges	Reduce `--margin` AND fix HTML width
Both issues	Content cut AND extra pages	Fix HTML CSS first, then adjust scale

Fix Strategy (Max 5 Attempts)

Attempt 1: Default settings

node scripts/html-to-pdf.js input.html output.pdf

Attempt 2: If vertical overflow → reduce scale

node scripts/html-to-pdf.js input.html output.pdf --scale=0.9

Attempt 3: If horizontal cut-off → reduce margins

node scripts/html-to-pdf.js input.html output.pdf --scale=0.9 --margin=10mm

Attempt 4: If still issues → smaller scale + margins

node scripts/html-to-pdf.js input.html output.pdf --scale=0.8 --margin=5mm

Attempt 5: If still failing → FIX THE HTML CSS:

/* Add to HTML to prevent horizontal overflow */
.container {
  width: 100%;
  max-width: 100%;
  overflow-wrap: break-word;
  word-wrap: break-word;
  box-sizing: border-box;
}

STOP after 5 attempts - regenerate HTML with proper constraints.

HTML Width Fix (Required for Horizontal Fit)

If content is cut at sides, the HTML MUST have:

html, body {
  width: 210mm;  /* A4 width */
  margin: 0;
  padding: 0;
  overflow: hidden;
}

.container {
  width: 100%;
  max-width: 100%;
  padding: 15mm;
  box-sizing: border-box;
  overflow-wrap: break-word;
}

Verification Checklist

After EVERY PDF generation, verify:

All text visible (not cut at edges)
No unnecessary empty pages
Content fills pages properly
No large gaps between sections

If ANY check fails → adjust and regenerate (max 5 times).

Technical Notes

Uses Puppeteer with Chrome headless for rendering
Waits for networkidle0 to ensure all resources load
Automatically waits for document.fonts.ready
Supports @page CSS rules for print styling
Device scale factor set to 2 for crisp rendering

Weekly Installs

446

Repository

aviz85/claude-s…-library

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykWarn

Installed on

opencode375

gemini-cli357

codex332

cursor328

github-copilot299

claude-code297

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

136,300 周安装