Here are some useful pointers for working with Paged.js, a valuable tool for creating precise PDFs from HTML using a preferred HTML to PDF API like Doppio. Detailed information is available in the Paged.js documentation.

Using the @media page Query with Paged.js

1. Setting Page Size and Margins:

Begin by adding a @page media query in your HTML's style tag. For example, to set an A4 page size with 20mm margins, use:

   @page {
       size: A4;
       margin: 20mm;
   }

The 'size' property specifies the page size (like A4, A3, A5), and 'margin' sets the page margins. These are typically in mm or cm, fitting standard document formats.

2. Doppio Parameter for Format Setting:

When using Doppio, set the format using:

   { "page": { "pdf": { "format": "A4" } } }

This ensures the PDF is rendered in the specified format.

The Sixteen Margin Boxes in Paged.js

1. Margin Box Customization:

Paged.js divides page margins into 16 areas for auto-generated elements like page numbers or headers, known as margin boxes. Customize each box with margin, border, padding, and content. Default sizes are based on the page box's margin, in line with W3C specifications.

2. Inserting Content into Margin Boxes:

For example, to add text to the top-center margin box:

   @page {
       size: A4;
       margin: 20mm;
       @top-center {
           vertical-align: center;
           text-align: center;
           background: #fafafa;
           color: purple;
           content: "Top-center margin";
       }
   }

This code adds "Top-center margin" in purple to the @top-center margin.

Counting Page Numbers in Paged.js

Displaying Page Numbers:

Use `content: "P. " counter(page);` in a margin box to show page numbers. For instance, in the bottom-right corner:

  @page {
      size: A4;
      margin: 20mm;
      @bottom-right-corner {
          vertical-align: center;
          text-align: center;
          background: #fafafa;
          color: purple;
          content: "P. " counter(page);
      }
  }

This will display the page number in purple in the bottom-right corner.

Starting New Pages in Paged.js

Manual Page Breaks:

Use `break-before: page;` on a CSS class to start new content on a new page:

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

These tips should help streamline your experience with Paged.js. For more comprehensive information, consult the full Paged.js documentation, and remember that some properties might already be preset in template models.