html-to-pdf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTML to PDF Converter

HTML转PDF转换器

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.

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

基于Puppeteer（无头Chrome）实现像素级精准的HTML转PDF转换。自动检测文本方向，完美支持希伯来语、阿拉伯语及其他RTL语言。

Why Puppeteer?

为什么选择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

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

CRITICAL: Fit Content to Single Page

关键提示：将内容适配单页

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

css

@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
```

html
或
body
元素设置背景会导致生成额外页面！请将背景样式放在容器元素上：

css

@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;
  background: linear-gradient(...); /* 背景样式写在这里 */
}

生成额外页面的常见原因：

在html/body上设置背景 - 务必放在
```
.container
```
元素上
内容溢出 - 使用
```
overflow: hidden
```
外边距/内边距导致内容超出

小贴士：

如果内容仍然溢出，使用
```
--scale=0.75 --margin=0
```
如需横向排版：使用
```
--landscape
```
参数

Setup (One-time)

首次设置（仅需一次）

Before first use, install dependencies:

bash

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

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

bash

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

Quick Usage

快速使用

Convert local HTML file:

转换本地HTML文件：

bash

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

bash

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

Convert URL to PDF:

转换URL为PDF：

bash

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

bash

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

Hebrew document with forced RTL:

强制RTL的希伯来语文档：

bash

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

bash

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

Pipe HTML content:

管道输入HTML内容：

bash

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

bash

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	20mm
`--margin-bottom=<value>`	Bottom margin	20mm
`--margin-left=<value>`	Left margin	20mm
`--scale=<number>`	Scale factor 0.1-2.0	1
`--background`	Print background graphics	true
`--no-background`	Don't print backgrounds	-
`--header=<html>`	Header HTML template	-
`--footer=<html>`	Footer HTML template	-
`--wait=<ms>`	Wait time for fonts/JS	1000
`--rtl`	Force RTL direction	auto-detect

参数	描述	默认值
`--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方向	自动检测

Examples

示例

Basic conversion:

基础转换：

bash

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

bash

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

Letter format with custom margins:

Letter格式自定义边距：

bash

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

bash

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

Hebrew invoice:

希伯来语发票：

bash

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

bash

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

Landscape presentation:

横向演示文稿：

bash

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

bash

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

No margins (full bleed):

无边距（全 bleed）：

bash

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

bash

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

Hebrew/RTL Best Practices

希伯来语/RTL最佳实践

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)

为了获得最佳的希伯来语渲染效果，你的HTML应遵循以下规范：

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

Example Hebrew HTML structure (single-page):

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

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; /* Background on container, NOT body */
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>שלום עולם</h1>
    <p>זהו מסמך בעברית</p>
  </div>
</body>
</html>

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>

Troubleshooting

故障排除

Fonts not rendering correctly

字体渲染异常

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

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

Hebrew appearing left-to-right

希伯来语显示为从左到右

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

使用
```
--rtl
```
参数强制RTL方向
为HTML元素添加
```
dir="rtl"
```
属性

Page breaks not working

分页不生效

Use CSS page-break properties:

css

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

使用CSS分页属性：

css

.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

确保已设置
```
--background
```
（默认开启）
仅当需要排除背景时使用
```
--no-background
```

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.

关键要求 - 每次生成PDF后，Claude必须执行以下步骤：

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

此步骤为必填项。绝不能在未进行视觉验证的情况下交付PDF。

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

问题	症状	修复方案
垂直溢出	页面底部有空白，内容跑到下一页	减小 `--scale` 参数
水平截断	文本在左右边缘被截断	减小 `--margin` 参数并修复HTML宽度
两种问题同时存在	内容被截断且存在空白页	先修复HTML/CSS，再调整缩放比例

Fix Strategy (Max 5 Attempts)

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

Attempt 1: Default settings

bash

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

Attempt 2: If vertical overflow → reduce scale

bash

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

Attempt 3: If horizontal cut-off → reduce margins

bash

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

Attempt 4: If still issues → smaller scale + margins

bash

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

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

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.

尝试1：默认设置

bash

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

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

bash

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

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

bash

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

尝试4：如果问题仍存在 → 进一步减小缩放比例和边距

bash

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

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

css

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

5次尝试后停止 - 重新生成符合约束条件的HTML。

HTML Width Fix (Required for Horizontal Fit)

HTML宽度修复（解决水平截断的必要步骤）

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

css

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;
}

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

css

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;
}

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).

每次生成PDF后，需验证：

所有文本可见（未被边缘截断）
无多余空白页
内容合理填充页面
各部分之间无大段空白

如果任何一项未通过 → 调整并重新生成（最多5次）。

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

使用Puppeteer和无头Chrome进行渲染
等待
```
networkidle0
```
状态以确保所有资源加载完成
自动等待
```
document.fonts.ready
```
事件
支持
```
@page
```
CSS规则进行打印样式设置
设备缩放系数设置为2，确保渲染清晰