> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pdfnoodle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PDF Best Practices Skill

> Comprehensive guidelines for creating HTML that renders perfectly as PDF

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.

<Tabs>
  <Tab title="npx skills (Recommended)">
    Install as an agent skill:

    ```bash theme={null}
    npx skills add pdfnoodle/pdf-best-practices
    ```

    This makes the skill available to AI coding assistants that support the skills protocol.
  </Tab>

  <Tab title="npm">
    Install via npm for programmatic access:

    ```bash theme={null}
    npm install pdf-best-practices
    ```
  </Tab>

  <Tab title="Direct Reference">
    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.
  </Tab>
</Tabs>

***

## What the Skill Covers

The skill includes 8 comprehensive guides:

<CardGroup cols={2}>
  <Card title="Document Setup" icon="file-code">
    HTML structure, base CSS, A4 specifications, and typography defaults.
  </Card>

  <Card title="Page Breaks" icon="scissors">
    Control where content splits with `page-break-inside`, `break-after`, and orphan/widow handling.
  </Card>

  <Card title="Tables" icon="table">
    Proper `thead`/`tbody` structure, header repetition, column widths, and zebra striping.
  </Card>

  <Card title="Images" icon="image">
    Explicit dimensions, `object-fit`, figures with captions, and image galleries.
  </Card>

  <Card title="Content Density" icon="layer-group">
    Avoid sparse pages, flexible spacing, and content reflow strategies.
  </Card>

  <Card title="Colors & Backgrounds" icon="palette">
    The critical `-webkit-print-color-adjust: exact` property and contrast guidelines.
  </Card>

  <Card title="Headers & Footers" icon="heading">
    Document headers, page numbers via `footerTemplate`, and letterhead patterns.
  </Card>

  <Card title="Document Types" icon="files">
    Specific guidelines for invoices, reports, certificates, letters, and more.
  </Card>
</CardGroup>

***

## Default Configuration

The skill recommends these PDF parameters:

```json theme={null}
{
  "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:

```css theme={null}
@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;
}
```

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

***

## Page Break Control

Prevent awkward content splits with these CSS properties:

```css theme={null}
/* 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:

```html theme={null}
<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>
```

```css theme={null}
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;
}
```

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

***

## Image Handling

Always specify explicit dimensions for images:

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

```css theme={null}
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:

1. **Estimating content height** before structuring documents
2. **Grouping related content** to flow naturally
3. **Using flexible spacing** instead of fixed large gaps
4. **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:

<AccordionGroup>
  <Accordion title="Invoice" icon="file-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
  </Accordion>

  <Accordion title="Report" icon="chart-bar">
    * Use title page for documents over 3 pages
    * Include table of contents
    * Page breaks before major sections
    * Consistent heading hierarchy
    * Executive summary at start
  </Accordion>

  <Accordion title="Certificate" icon="award">
    * Center all content
    * Larger fonts (18-36pt)
    * Decorative borders
    * Single page only
    * Consider landscape orientation
  </Accordion>

  <Accordion title="Letter" icon="envelope">
    * Standard business letter format
    * Letterhead with logo
    * Clear date and recipient block
    * Signature area at bottom
    * 1-2 pages maximum
  </Accordion>
</AccordionGroup>

***

## Quick Checklist

Before generating any PDF:

<Checklist>
  * Complete HTML structure (DOCTYPE, html, head, body)
  * `@page` rule with A4 size
  * Body has `-webkit-print-color-adjust: exact`
  * All images have explicit width/height
  * Tables use `thead`/`tbody` structure
  * `page-break-inside: avoid` on content blocks
  * Headings have `page-break-after: avoid`
  * No sparse pages (\< 25% content)
  * Font sizes 9pt or larger
  * pdfParams includes `printBackground: true`
</Checklist>

***

## Complete Starter Template

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

```html theme={null}
<!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>
```

***

## Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/pdfnoodle/pdf-best-practices">
    Full skill source with all guides
  </Card>

  <Card title="npm Package" icon="npm" href="https://www.npmjs.com/package/pdf-best-practices">
    Install via npm
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Examples" icon="lightbulb" href="/integrations/mcp/examples">
    See the skill in action
  </Card>

  <Card title="Tools Reference" icon="wrench" href="/integrations/mcp/tools">
    All MCP tools documentation
  </Card>
</CardGroup>