PDF Best Practices Skill

When using the html_to_pdf tool, the quality of your output depends entirely on how well the HTML is structured for print. The PDF Best Practices skill provides AI assistants with comprehensive guidelines to create professional, well-formatted PDF documents.

HTML Content  ──▶  CSS Styles  ──▶  PDF Engine  ──▶  Page Layout  ──▶  Final PDF
                                   (Puppeteer)      & Margins

Installing the Skill

The PDF Best Practices skill is available as a standalone package that AI assistants can reference.

npx skills (Recommended)
npm
Direct Reference

Install as an agent skill:

npx skills add pdfnoodle/pdf-best-practices

This makes the skill available to AI coding assistants that support the skills protocol.

Install via npm for programmatic access:

npm install pdf-best-practices

AI assistants can reference the skill directly from GitHub:

https://github.com/pdfnoodle/pdf-best-practices

The SKILL.md file serves as the entry point with links to detailed guides.

What the Skill Covers

The skill includes 8 comprehensive guides:

Document Setup

HTML structure, base CSS, A4 specifications, and typography defaults.

Page Breaks

Control where content splits with page-break-inside, break-after, and orphan/widow handling.

Tables

Proper thead/tbody structure, header repetition, column widths, and zebra striping.

Images

Explicit dimensions, object-fit, figures with captions, and image galleries.

Content Density

Avoid sparse pages, flexible spacing, and content reflow strategies.

Colors & Backgrounds

The critical -webkit-print-color-adjust: exact property and contrast guidelines.

Headers & Footers

Document headers, page numbers via footerTemplate, and letterhead patterns.

Document Types

Specific guidelines for invoices, reports, certificates, letters, and more.

Default Configuration

The skill recommends these PDF parameters:

{
  "format": "A4",
  "margin": {
    "top": "40px",
    "right": "40px",
    "bottom": "40px",
    "left": "40px"
  },
  "printBackground": true
}

A4 Paper Specifications

Property	Value
Width	210mm (794px at 96 DPI)
Height	297mm (1123px at 96 DPI)
Safe content width	~714px (with 40px margins)
Safe content height	~1043px per page

Essential CSS Rules

Every HTML-to-PDF document should include these CSS rules:

@page {
  size: A4;
  margin: 40px;
}

* {
  box-sizing: border-box;
}

html, body {
  margin: 0;
  padding: 0;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Arial, sans-serif;
  font-size: 12pt;
  line-height: 1.5;
  color: #333;
}

body {
  -webkit-print-color-adjust: exact;
  print-color-adjust: exact;
}

The -webkit-print-color-adjust: exact property is critical. Without it, background colors may not appear in the generated PDF.

Page Break Control

Prevent awkward content splits with these CSS properties:

/* Prevent breaks inside elements */
.section, .card, figure, tr {
  page-break-inside: avoid;
  break-inside: avoid;
}

/* Keep headings with following content */
h1, h2, h3 {
  page-break-after: avoid;
  break-after: avoid;
}

/* Orphan/widow control for paragraphs */
p {
  orphans: 3;
  widows: 3;
}

When to Use Page Breaks

Use `page-break-inside: avoid` on	Use `page-break-before: always` on
Cards and content boxes	Chapter starts
Table rows	Major sections
Figures with captions	New document parts
List items with multiple lines	Title pages

Table Formatting

Tables require special attention for multi-page documents:

<table>
  <thead>
    <tr>
      <th>Column 1</th>
      <th>Column 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Data 1</td>
      <td>Data 2</td>
    </tr>
  </tbody>
</table>

table {
  width: 100%;
  border-collapse: collapse;
  font-size: 11pt;
  table-layout: fixed;
}

th, td {
  border: 1px solid #ddd;
  padding: 8px 12px;
  text-align: left;
}

th {
  background-color: #f5f5f5;
}

tr {
  page-break-inside: avoid;
}

Always use <thead> and <tbody> structure. This allows PDF engines to repeat headers on each page when tables span multiple pages.

Image Handling

Always specify explicit dimensions for images:

<figure>
  <img
    src="https://example.com/image.jpg"
    width="300"
    height="200"
    alt="Description"
  >
  <figcaption>Figure 1: Image caption</figcaption>
</figure>

img {
  max-width: 100%;
  height: auto;
}

figure {
  page-break-inside: avoid;
  margin: 20px 0;
  text-align: center;
}

figcaption {
  margin-top: 8px;
  font-size: 10pt;
  color: #666;
}

Image Guidelines

Use absolute URLs (https://…) for all images
Set max-height to 300-400px to fit well on pages
Group images with captions using <figure>
Use object-fit: contain to preserve aspect ratios

Content Density

Avoid pages with minimal content by:

Estimating content height before structuring documents
Grouping related content to flow naturally
Using flexible spacing instead of fixed large gaps
Reducing margins slightly if the last page is sparse

Reflow Strategies

If the last page has less than 25% content:

Reduce margins: 35px instead of 40px
Tighten line-height: 1.4 instead of 1.5
Reduce section margins
Use slightly smaller font for dense data (11pt)

Document Type Guidelines

The skill includes specific recommendations for common document types:

Invoice

Keep entire invoice on one page if possible
Right-align all monetary values
Use clear table for line items
Include totals section that stays with items table
Add payment terms prominently

Report

Use title page for documents over 3 pages
Include table of contents
Page breaks before major sections
Consistent heading hierarchy
Executive summary at start

Certificate

Center all content
Larger fonts (18-36pt)
Decorative borders
Single page only
Consider landscape orientation

Letter

Standard business letter format
Letterhead with logo
Clear date and recipient block
Signature area at bottom
1-2 pages maximum

Quick Checklist

Before generating any PDF:

Complete Starter Template

Use this template as a starting point for custom HTML-to-PDF documents:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <style>
    @page {
      size: A4;
      margin: 40px;
    }

    * {
      box-sizing: border-box;
    }

    html, body {
      margin: 0;
      padding: 0;
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Arial, sans-serif;
      font-size: 12pt;
      line-height: 1.5;
      color: #333;
    }

    body {
      -webkit-print-color-adjust: exact;
      print-color-adjust: exact;
    }

    h1, h2, h3 {
      page-break-after: avoid;
    }

    h1 { font-size: 24pt; margin: 0 0 20px 0; }
    h2 { font-size: 18pt; margin: 30px 0 15px 0; }

    p {
      margin: 0 0 12px 0;
      orphans: 3;
      widows: 3;
    }

    .section {
      page-break-inside: avoid;
      margin-bottom: 20px;
    }

    table {
      width: 100%;
      border-collapse: collapse;
      margin: 16px 0;
    }

    th, td {
      border: 1px solid #ddd;
      padding: 10px;
      text-align: left;
    }

    th {
      background-color: #f5f5f5;
    }

    tr {
      page-break-inside: avoid;
    }
  </style>
</head>
<body>
  <h1>Document Title</h1>

  <div class="section">
    <h2>Section 1</h2>
    <p>Content goes here...</p>
  </div>

  <div class="section">
    <h2>Section 2</h2>
    <table>
      <thead>
        <tr>
          <th>Column 1</th>
          <th>Column 2</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>Data 1</td>
          <td>Data 2</td>
        </tr>
      </tbody>
    </table>
  </div>
</body>
</html>

MCP Integration

Installing the Skill

What the Skill Covers

Document Setup

Page Breaks

Tables

Images

Content Density

Colors & Backgrounds

Headers & Footers

Document Types

Default Configuration

A4 Paper Specifications

Essential CSS Rules

Page Break Control

When to Use Page Breaks

Table Formatting

Image Handling

Image Guidelines

Content Density

Reflow Strategies

Document Type Guidelines

Quick Checklist

Complete Starter Template

Resources

GitHub Repository

npm Package

Next Steps

Examples

Tools Reference

MCP Integration

​Installing the Skill

​What the Skill Covers

Document Setup

Page Breaks

Tables

Images

Content Density

Colors & Backgrounds

Headers & Footers

Document Types

​Default Configuration

​A4 Paper Specifications

​Essential CSS Rules

​Page Break Control

​When to Use Page Breaks

​Table Formatting

​Image Handling

​Image Guidelines

​Content Density

​Reflow Strategies

​Document Type Guidelines

​Quick Checklist

​Complete Starter Template

​Resources

GitHub Repository

npm Package

​Next Steps

Examples

Tools Reference

Installing the Skill

What the Skill Covers

Default Configuration

A4 Paper Specifications

Essential CSS Rules

Page Break Control

When to Use Page Breaks

Table Formatting

Image Handling

Image Guidelines

Content Density

Reflow Strategies

Document Type Guidelines

Quick Checklist

Complete Starter Template

Resources

Next Steps