HTML To PDF

Source: https://github.com/aipoch/medical-research-skills

Validation Shortcut

Run this minimal command first to verify the supported execution path:

python scripts/validate_skill.py --help

When to Use

• Export a web page (URL) to a PDF with Chrome-accurate rendering (CSS Grid/Flexbox, backgrounds, web fonts).
• Convert a local HTML report/invoice into a print-ready PDF (A4/Letter) with predictable margins and scaling.
• Generate single-page PDFs that must fit exactly on one page (posters, certificates, one-page invoices).
• Produce RTL documents (Hebrew/Arabic) where direction must be correct and fonts must render reliably.
• Render dynamic HTML that requires JavaScript execution before printing (charts, client-side templates).

Key Features

• Chrome-quality rendering via Puppeteer (headless Chromium/Chrome/Edge).
• Input flexibility: local HTML file, URL, or stdin (-) piping.
• RTL support: automatic RTL detection with an option to force RTL (--rtl).
• Print controls: format, landscape, margins (uniform or per-side), scale, background printing.
• Header/Footer templates: inject HTML header/footer.
• Stability for fonts/resources: waits for network idle and document.fonts.ready, plus configurable extra wait.

Dependencies

• Node.js: >= 16 (recommended)
• npm: >= 8
• puppeteer: installed via npm install (Chromium bundled by default)
• Optional browser executable (if not using bundled Chromium):
  • Google Chrome or Microsoft Edge (path provided via --executable-path or PUPPETEER_EXECUTABLE_PATH)

Example Usage

1) Install

cd d:/skills/html-to-pdf
npm install

2) Run (local HTML → PDF)

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

3) Run (URL → PDF)

node assets/html-to-pdf.js https://example.com page.pdf

4) Force RTL (Hebrew/Arabic)

node assets/html-to-pdf.js hebrew.html hebrew.pdf --rtl

5) Pipe HTML via stdin

echo "<h1>Example Title</h1>" | node assets/html-to-pdf.js - output.pdf --rtl

6) Use a specific browser executable (optional)

node assets/html-to-pdf.js https://example.com page.pdf --executable-path="C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"

Or via environment variable:

set PUPPETEER_EXECUTABLE_PATH=C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
node assets/html-to-pdf.js https://example.com page.pdf

7) A complete, runnable single-page A4 example (recommended pattern)

Create single-page.html:

<!doctype html>
<html lang="he" dir="rtl">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <link href="https://fonts.googleapis.com/css2?family=Heebo:wght@400;700&display=swap" rel="stylesheet">
  <style>
    @page { size: A4; margin: 0; }

    /* Keep the page box exact; avoid backgrounds here to prevent extra pages */
    html, body {
      width: 210mm;
      height: 297mm;
      margin: 0;
      padding: 0;
      overflow: hidden;
    }

    /* Put backgrounds on a full-size container instead */
    .container {
      width: 100%;
      height: 100%;
      box-sizing: border-box;
      padding: 20mm;

      font-family: "Heebo", sans-serif;
      direction: rtl;
      text-align: right;

      background: #f5f5f5;
      overflow-wrap: break-word;
      word-wrap: break-word;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>כותרת לדוגמה</h1>
    <p>תוכן לדוגמה שמודפס כעמוד יחיד.</p>
  </div>
</body>
</html>

Generate the PDF:

node assets/html-to-pdf.js single-page.html single-page.pdf --format=A4 --margin=0 --wait=1000

Implementation Details

Rendering approach

• Uses Puppeteer to load either:
  • a local HTML file, or
  • a remote URL, or
  • HTML from stdin (-)
• Wait strategy (to reduce missing fonts/assets):
  • waits for networkidle0 (resources finished loading),
  • waits for document.fonts.ready,
  • then waits an additional --wait=<ms> (default 1000) for late JS/font rendering.

RTL handling

• Default behavior: auto-detect RTL content (e.g., Hebrew/Arabic) and apply RTL direction.
• Override: --rtl forces RTL regardless of detection.

Page-fit rule (single-page PDFs)

To avoid unexpected blank pages, ensure the content fits exactly within the page box:

• Do not set backgrounds on html or body (common cause of extra pages).
• Put backgrounds on a full-height container (.container) instead.
• Use overflow: hidden on html, body for strict single-page output.
• If overflow persists, adjust:
  • --scale (e.g., 0.9, 0.8)
  • --margin (e.g., 10mm, 0)

CLI parameters

Quality settings

• Uses Chrome print styles (@page) and supports print CSS.
• Sets deviceScaleFactor to 2 to improve output clarity.

Verification workflow (recommended)

After each generation, visually verify the PDF:

• No extra blank pages (vertical overflow).
• No clipped text (horizontal overflow).
• If issues occur, iterate up to 5 attempts:
  1. default
  2. reduce --scale
  3. reduce --margin
  4. reduce both further
  5. fix HTML/CSS (wrap long words, ensure container sizing)

If it still fails after 5 attempts, the HTML layout must be corrected (e.g., reduce fixed heights, fix oversized elements, ensure wrapping).

When Not to Use

• Do not use this skill when the required source data, identifiers, files, or credentials are missing.
• Do not use this skill when the user asks for fabricated results, unsupported claims, or out-of-scope conclusions.
• Do not use this skill when a simpler direct answer is more appropriate than the documented workflow.