Dynamic Page Numbers & Running Headers

Technical Deep Dive & Specifications

1. The 16 Margin Boxes & Content Injection

Inside an @page rule, you can define margin box rules using standard CSS pseudo-declarations:

@page {
  size: A4 portrait;
  margin: 25mm 20mm;

  /* Top Left: Organization Name */
  @top-left {
    content: "Acme Cloud Infrastructure Corp.";
    font-family: sans-serif;
    font-size: 8pt;
    color: #64748b;
  }

  /* Top Right: Running Section Title */
  @top-right {
    content: "Confidential & Proprietary";
    font-family: sans-serif;
    font-size: 8pt;
    font-weight: bold;
    color: #dc2626;
  }

  /* Bottom Center: Page Counter */
  @bottom-center {
    content: "Page " counter(page) " of " counter(pages);
    font-family: sans-serif;
    font-size: 9pt;
  }
}

2. The Built-in CSS Page Counters

The CSS Paged Media specification specifies two native counters:

1. counter(page): Returns the current physical page number (1-indexed).
2. counter(pages): Returns the total number of pages in the printed document.

/* Custom counter formatting */
@page {
  @bottom-right {
    /* Formats: decimal (1, 2, 3), lower-roman (i, ii, iii), upper-roman (I, II, III), lower-alpha (a, b, c) */
    content: "Sheet " counter(page, upper-roman);
  }
}

/* Suppress counters on the cover page */
@page :first {
  @top-left { content: none; }
  @top-right { content: none; }
  @bottom-center { content: none; }
}

3. Dynamic Running Headers with string-set()

To pull text dynamically from the HTML content (such as the current <h2> heading) and print it inside @top-right, the specification defines string-set():

/* Capture the text content of the active h2 heading */
h2 {
  string-set: chapter-title content();
}

/* Inject the captured text into the margin box */
@page {
  @top-right {
    content: string(chapter-title);
    font-style: italic;
  }
}

4. Real-World Browser Support vs. Headless PDF Engines

Understanding the browser implementation reality is crucial for senior engineers:

+-----------------------------------------------------------------------------------+
|               CSS PAGED MEDIA MARGIN BOX ENGINE COMPATIBILITY                      |
+-----------------------------------------------------------------------------------+
  Feature                      PrinceXML / WeasyPrint    Chromium / Puppeteer / Safari
  ---------------------------------------------------------------------------------
  @page { margin }             ✅ Full Support           ✅ Full Support
  @top-left, @bottom-right     ✅ Full Support           ❌ Limited / No Native CSS
  counter(page), counter(pages)✅ Full Support           ❌ (Use Puppeteer Templates)
  string-set()                 ✅ Full Support           ❌ Not in WebKit/Blink

[!IMPORTANT]

• In Pure CSS Engines (PrinceXML, WeasyPrint, Paged.js, Typeset.sh): Margin boxes (@top-center, @bottom-right, counter(page)) work natively via CSS.
• In Chromium / Puppeteer / Playwright: You generate running headers and dynamic page counts using HTML/CSS template parameters in the PDF generation API: page.pdf({ displayHeaderFooter: true, headerTemplate: '...', footerTemplate: '...' }) (Mastered in Lesson 89.8).
• In Paged.js (Polyfill for standard browsers): Translates W3C margin boxes into simulated DOM elements in standard Chrome/Firefox.

💻 Interactive Code Playground

Below is a complete, runnable HTML document demonstrating standard CSS Paged Media margin boxes, counter formatting, and cover page suppression.

Starter Code

Line-by-Line Code Breakdown

• Lines 8–13 (@page): Establishes A4 geometry with $30\text{mm}$ top/bottom margins to allocate vertical breathing room for margin boxes.
• Lines 16–24 (@top-left): Renders company branding with a subtle bottom divider line (border-bottom: 0.5pt solid #cbd5e1).
• Lines 36–43 (@bottom-left): Injects red security classification text with a top divider line.
• Lines 45–53 (@bottom-right): Generates dynamic page counts: "Page " counter(page) " of " counter(pages).
• Lines 57–63 (@page :first): Suppresses headers and footers on the cover page using content: none; border: none;.

Expected Browser Render Output

• Screen View: Displays three clean, stacked document pages with realistic dropshadows.
• In Paged Media Engines (PrinceXML / Paged.js / Print Preview):
  • Page 1 has no running headers or footers.
  • Page 2 displays top header ("ACME CORP..." and "PROJECT TITAN") and bottom footer ("CONFIDENTIAL..." and "Page 2 of 3").
  • Page 3 displays identical top headers and "Page 3 of 3".