Template Styling

Learn how to style your PDF documents with advanced CSS features including page formatting, headers, footers, page breaks, and more.

Page Formatting with @page

The @page CSS rule allows you to control PDF page properties such as margins, headers, footers, and page numbers.

Adding Styles to Your Templates

You can add these CSS styles to your templates in two ways:

Via Dashboard

1. Go to Templates Dashboard
2. Create a new template or edit an existing one
3. Find the “Extra CSS” field
4. Paste your @page rules and styling code
5. Save your template

Via API

Include the styles in the extra_css parameter when creating or updating templates:

{
  "template_id": "template-id",
  "name": "Invoice Template",
  "content": "<h1>Invoice</h1>",
  "extra_css": "@page { margin: 2cm; @bottom-center { content: 'Page ' counter(page); } }"
}

Note: The “Content” field is for your HTML template, while “Extra CSS” is specifically for PDF page styling and @page rules.

Basic Page Margins

Set margins for all pages:

@page {
  margin: 2cm; /* All sides */
}

Set different margins for each side:

@page {
  margin-top: 3cm;
  margin-bottom: 2cm;
  margin-left: 1.5cm;
  margin-right: 1.5cm;
}

Shorthand for top/bottom and left/right:

@page {
  margin: 2cm 1cm; /* Top/bottom: 2cm, Left/right: 1cm */
}

Page Size and Orientation

Standard paper sizes:

@page {
  size: A4; /* A4 paper (210mm × 297mm) */
}

@page {
  size: Letter; /* US Letter (8.5in × 11in) */
}

@page {
  size: Legal; /* US Legal (8.5in × 14in) */
}

@page {
  size: A3; /* A3 paper (297mm × 420mm) */
}

Landscape orientation:

@page {
  size: A4 landscape;
}

@page {
  size: Letter landscape;
}

Custom page dimensions:

@page {
  size: 210mm 297mm; /* Custom width and height */
}

@page {
  size: 8.5in 11in; /* Using inches */
}

---

Headers and Footers

Place content in page margins using margin box rules.

Available Positions

Top margin boxes:

• @top-left - Top left corner
• @top-center - Top center
• @top-right - Top right corner

Bottom margin boxes:

• @bottom-left - Bottom left corner
• @bottom-center - Bottom center
• @bottom-right - Bottom right corner

Side margin boxes:

• @left-top, @left-middle, @left-bottom - Left side
• @right-top, @right-middle, @right-bottom - Right side

Footer Examples

Simple footer text:

@page {
  @bottom-left {
    content: "♥ Thank you for your business!";
    color: #1ee494;
    font-size: 10pt;
  }
}

Company information:

@page {
  @bottom-center {
    content: "ACME Corporation | support@acme.com | +1-555-0123";
    font-size: 9pt;
    color: #666;
    font-family: Arial, sans-serif;
  }
}

Copyright notice:

@page {
  @bottom-left {
    content: "© 2025 ACME Corp. All rights reserved.";
    font-size: 8pt;
    color: #999;
    font-style: italic;
  }
}

Header Examples

Company name:

@page {
  @top-left {
    content: "ACME Corporation";
    font-weight: bold;
    font-size: 12pt;
    color: #333;
  }
}

Document title:

@page {
  @top-center {
    content: "INVOICE";
    font-size: 14pt;
    font-weight: bold;
    color: #2c3e50;
    letter-spacing: 2px;
  }
}

Date or document info:

@page {
  @top-right {
    content: "Confidential";
    font-size: 10pt;
    color: #e74c3c;
    font-weight: bold;
  }
}

---

Page Numbers

---

Simple Page Number

@page {
  @bottom-center {
    content: counter(page);
    font-size: 10pt;
  }
}

Page X of Y Format

@page {
  @bottom-right {
    content: "Page " counter(page) " of " counter(pages);
    font-size: 9pt;
    color: #666;
  }
}

Styled Page Numbers

@page {
  @bottom-center {
    content: "— " counter(page) " —";
    font-size: 10pt;
    color: #999;
    font-family: Georgia, serif;
  }
}

Page Numbers with Text

@page {
  @bottom-left {
    content: "Invoice Page " counter(page);
    font-size: 9pt;
    font-weight: bold;
  }
}

---

Multiple Headers and Footers

Combine multiple margin boxes for complete page decoration:

@page {
  margin: 2.5cm 2cm;

  /* Headers */
  @top-left {
    content: "ACME Corporation";
    font-size: 10pt;
    color: #333;
    font-weight: bold;
  }

  @top-center {
    content: "SALES INVOICE";
    font-size: 11pt;
    color: #666;
    letter-spacing: 1px;
  }

  @top-right {
    content: "Date: " attr(data-date);
    font-size: 9pt;
    color: #666;
  }

  /* Footers */
  @bottom-left {
    content: "♥ Thank you!";
    font-size: 9pt;
    color: #1ee494;
  }

  @bottom-center {
    content: "www.acme.com | support@acme.com";
    font-size: 8pt;
    color: #999;
  }

  @bottom-right {
    content: "Page " counter(page) " of " counter(pages);
    font-size: 9pt;
    color: #666;
  }
}

---

First Page Styling

Style the first page differently from other pages:

/* First page - no header, extra top margin for letterhead */
@page :first {
  margin-top: 5cm;

  @top-left {
    content: ""; /* Remove header */
  }

  @top-center {
    content: "";
  }

  @top-right {
    content: "";
  }
}

/* All other pages - normal headers */
@page {
  margin-top: 2.5cm;

  @top-center {
    content: "Invoice - Continued";
    font-size: 10pt;
    color: #666;
  }
}

Example with letterhead:

@page :first {
  margin-top: 6cm; /* Space for logo/letterhead */

  @top-center {
    content: ""; /* No header on first page */
  }

  @bottom-center {
    content: "Thank you for choosing ACME";
    font-size: 10pt;
    color: #1ee494;
  }
}

@page {
  margin-top: 2cm;

  @top-center {
    content: "ACME Corporation - Page " counter(page);
  }
}

---

Page Breaks

Control how content flows across pages.

Force Page Break

Break before an element:

.new-section {
  page-break-before: always;
}

.chapter-start {
  page-break-before: always;
}

Break after an element:

.section-end {
  page-break-after: always;
}

.cover-page {
  page-break-after: always;
}

Prevent Page Breaks

Keep element together:

.keep-together {
  page-break-inside: avoid;
}

/* Keep table rows together */
table tr {
  page-break-inside: avoid;
}

/* Keep sections together */
.info-section {
  page-break-inside: avoid;
}

Prevent breaks after headings:

h1,
h2,
h3,
h4,
h5,
h6 {
  page-break-after: avoid;
  page-break-inside: avoid;
}

Smart Page Breaks

/* Avoid widows (single line at top of page) */
p {
  widows: 2;
  orphans: 2;
}

/* Keep heading with following content */
h2 {
  page-break-after: avoid;
}

h2 + p {
  page-break-before: avoid;
}

---

Named Pages

Create different page styles for different sections:

/* Define page types */
@page cover {
  margin: 0;
  size: A4;

  @top-center {
    content: ""; /* No headers on cover */
  }

  @bottom-center {
    content: ""; /* No footers on cover */
  }
}

@page content {
  margin: 2cm;
  size: A4;

  @top-center {
    content: "Document Title";
  }

  @bottom-right {
    content: "Page " counter(page);
  }
}

@page appendix {
  margin: 1.5cm;

  @top-center {
    content: "Appendix";
    font-style: italic;
  }
}

Apply page styles to elements:

<style>
  .cover-page {
    page: cover;
  }

  .main-content {
    page: content;
  }

  .appendix-section {
    page: appendix;
  }
</style>

<div class="cover-page">
  <h1>Invoice</h1>
</div>

<div class="main-content">
  <!-- Main invoice content -->
</div>

<div class="appendix-section">
  <!-- Terms and conditions -->
</div>

---

Complete Styling Examples

---

Professional Invoice

@page {
  margin: 2.5cm 2cm;
  size: A4;

  @top-left {
    content: "ACME Corporation";
    font-family: Arial, sans-serif;
    font-size: 11pt;
    font-weight: bold;
    color: #2c3e50;
  }

  @top-right {
    content: "Invoice #" counter(page);
    font-family: Arial, sans-serif;
    font-size: 10pt;
    color: #7f8c8d;
  }

  @bottom-left {
    content: "♥ Thank you for your business!";
    font-family: Arial, sans-serif;
    font-size: 9pt;
    color: #1ee494;
  }

  @bottom-center {
    content: "123 Business St, New York, NY 10001 | +1-555-0123 | billing@acme.com";
    font-family: Arial, sans-serif;
    font-size: 8pt;
    color: #95a5a6;
  }

  @bottom-right {
    content: "Page " counter(page) " of " counter(pages);
    font-family: Arial, sans-serif;
    font-size: 9pt;
    color: #7f8c8d;
  }
}

@page :first {
  @top-left {
    content: "";
  }
  @top-right {
    content: "";
  }
}

Certificate with Border

@page {
  margin: 1cm;
  size: A4 landscape;

  @bottom-center {
    content: "Certificate #" counter(page) " | Issued by ACME Academy";
    font-family: Georgia, serif;
    font-size: 9pt;
    color: #666;
    font-style: italic;
  }
}

Multi-Section Report

/* Cover page */
@page cover {
  margin: 0;
  size: A4;
}

/* Table of contents */
@page toc {
  margin: 2cm;

  @top-center {
    content: "Table of Contents";
    font-size: 12pt;
    font-weight: bold;
  }

  @bottom-right {
    content: counter(page, lower-roman);
  }
}

/* Main content pages */
@page content {
  margin: 2.5cm 2cm;

  @top-left {
    content: "Annual Report 2025";
    font-size: 10pt;
    color: #666;
  }

  @top-right {
    content: "ACME Corporation";
    font-size: 10pt;
    color: #666;
  }

  @bottom-center {
    content: "— " counter(page) " —";
    font-size: 10pt;
  }
}

/* Appendix pages */
@page appendix {
  margin: 2cm;

  @top-center {
    content: "Appendix";
    font-style: italic;
  }

  @bottom-center {
    content: "A-" counter(page);
  }
}

---

Page Break Examples in HTML

---

Invoice with Page Breaks

<!DOCTYPE html>
<html>
  <head>
    <style>
      body {
        font-family: Arial, sans-serif;
      }

      .invoice-header {
        page-break-after: avoid;
      }

      .line-items table {
        width: 100%;
        border-collapse: collapse;
      }

      .line-items tr {
        page-break-inside: avoid;
      }

      .terms-section {
        page-break-before: always;
      }

      .signature-section {
        page-break-inside: avoid;
        margin-top: 50px;
      }
    </style>
  </head>
  <body>
    <div class="invoice-header">
      <h1>INVOICE</h1>
      <p>Invoice #: {{ invoice_number }}</p>
    </div>

    <div class="line-items">
      <table>
        <!-- Items here -->
      </table>
    </div>

    <div class="terms-section">
      <h2>Terms and Conditions</h2>
      <p>Payment terms...</p>
    </div>

    <div class="signature-section">
      <p>Authorized Signature: _________________</p>
    </div>
  </body>
</html>

---

Tips and Best Practices

✅ Do’s

• Use appropriate margins - Minimum 1cm for printing, 1.5-2cm recommended
• Test multi-page documents - Ensure headers/footers appear correctly
• Keep headers/footers simple - Too much content can look cluttered
• Use page-break-inside: avoid - For tables, images, and important sections
• Consistent font sizing - Headers/footers should be 8-11pt
• Consider print margins - Leave space for binding if needed

❌ Don’ts

• Don’t use margins < 0.5cm - Content may be cut off when printing
• Don’t forget first page styling - Often needs different layout
• Don’t use background images in @page - Limited support
• Don’t place large content in margins - Keep it concise
• Don’t forget page break testing - Test with various content lengths
• Don’t use too many different fonts - Keep it professional

---

Common Use Cases

---

Business Letter

@page {
  margin: 2.5cm 2cm 2cm 2cm;
  size: Letter;

  @bottom-center {
    content: "Page " counter(page);
    font-size: 9pt;
    color: #999;
  }
}

@page :first {
  margin-top: 8cm; /* Space for letterhead */

  @bottom-center {
    content: ""; /* No page number on first page */
  }
}

Legal Document

@page {
  margin: 3cm 2.5cm;
  size: Legal;

  @top-center {
    content: "Contract Agreement";
    font-size: 11pt;
    font-weight: bold;
  }

  @bottom-left {
    content: "Confidential & Proprietary";
    font-size: 8pt;
    color: #e74c3c;
    font-style: italic;
  }

  @bottom-right {
    content: "Page " counter(page) " of " counter(pages);
    font-size: 9pt;
  }
}

Product Catalog

@page {
  margin: 1.5cm;
  size: A4;

  @top-left {
    content: "ACME Product Catalog 2025";
    font-size: 10pt;
    color: #666;
  }

  @top-right {
    content: "www.acme.com";
    font-size: 9pt;
    color: #1ee494;
  }

  @bottom-center {
    content: counter(page);
    font-size: 11pt;
    font-weight: bold;
  }
}

Restaurant Menu

@page {
  margin: 1cm;
  size: A4;

  @bottom-center {
    content: "The Gourmet Restaurant | Reservations: +1-555-FOOD";
    font-size: 8pt;
    color: #666;
    font-family: Georgia, serif;
  }
}

---

Troubleshooting

---

Headers/Footers Not Showing

Problem: Content not appearing in margin boxes

Solutions:

• Ensure margins are large enough (minimum 1cm)
• Check for typos in margin box names
• Verify content property is set
• Test with simple text first

Content Cut Off

Problem: Content disappearing at page edges

Solutions:

• Increase page margins
• Use page-break-inside: avoid on important elements
• Test with different paper sizes
• Reduce content size in margin boxes

Page Breaks in Wrong Places

Problem: Content breaking awkwardly

Solutions:

• Add page-break-inside: avoid to keep sections together
• Use page-break-after: avoid on headings
• Increase widows and orphans values
• Test with realistic content length

---

Need Help?

If you have questions about applications or need assistance:

• 📧 Email: support@docstron.com
• 💬 Live Chat: Available in your dashboard
• 📚 Documentation: You’re reading it!