Docly Developers
Knowledge base Pitfall Workaround available

htmlToPdf shrinks the page to about 71 percent

In shortdocly.htmlToPdf does not print one CSS pixel as 0.75 pt the way a browser's print does. The page is laid out roughly 1100 px wide and shrunk onto the paper, so everything comes out at about 71 % of its size with <!-- ChromePDF csspagesize --> and about 66 % without it: 16 px body text prints as 8.5 pt, and spacing that looks generous on screen looks cramped on paper. The 1920×1280 viewport in the reference is what scripts in the page see, not the width the print is laid out at. Every length in the content is scaled, mm and pt included; only @page margins are not. With csspagesize, html{zoom:1.4142} restores 1 px = 0.75 pt. Measure the result with pdftotext -bbox rather than judging it by eye.
Applies to APIPDF
  1. What you'll see

    You build a PDF with docly.htmlToPdf from HTML that looks right in the browser, and the PDF comes out small and cramped. Body text that is 16 px on screen reads like a footnote, and padding you already doubled still looks tight. Adding more space changes nothing that you can see, because everything you add shrinks in the same way.

    return docly.htmlToPdf("report.pdf",
        '<!-- ChromePDF csspagesize --><style>@page{size:A4;margin:20mm}</style>'
      + '<body style="font:16px Arial">…</body>');   // prints as about 8.5 pt
  2. What's actually happening

    The print is laid out wider than the paper and then scaled down to fit. In ordinary browser print, one CSS pixel is 1/96 inch, which is 0.75 pt, and an A4 sheet is 794 px wide. htmlToPdf does not follow that. Measured on 2026-11-21 with absolutely positioned markers at left:500px and left:1000px, reading the word positions back with pdftotext -bbox:

    Setup500 px became1 pxScaleWidth laid out
    <!-- ChromePDF csspagesize -->, @page{size:A4;margin:0}266 pt0.53 pt71 %about 1117 px across the sheet
    No options (default margins of about 10 mm)247 pt0.49 pt66 %about 1092 px between the margins
    Ordinary browser print, for comparison375 pt0.75 pt100 %794 px across the sheet

    The 1920×1280 viewport is not the print width. The htmlToPdf reference says the page is rendered in a 1920×1280 viewport, and that is true for scripts: a script in the page reads innerWidth 1920, innerHeight 1280 and devicePixelRatio 1. The print layout is a separate pass at about 1100 px, so a measurement taken in a script tells you nothing about the size on paper.

    The scale applies to every length in the content. That includes mm, cm and pt, not only px. A block with height:297mm is about 210 mm tall on the sheet. The margins in @page are the exception: they are applied to the paper and are not scaled.

  3. What to do

    Compensate with zoom, and set the page size yourself

    Use <!-- ChromePDF csspagesize --> so that @page decides the paper size and the margins, and put zoom on the root element to undo the scale. 1.4142 brings 1 px back to 0.75 pt (0.53 × 1.4142 ≈ 0.75):

    <!-- ChromePDF csspagesize -->
    <style>
      @page{size:A4;margin:22mm 0 20mm}   /* applied to the paper, not scaled */
      @page:first{margin:0}
      html{zoom:1.4142}                    /* undoes the ~71 % scale: 1 px prints as 0.75 pt again */
    </style>

    With that in place you can write the CSS in the sizes you would use for ordinary print. A full-page cover needs a little room for rounding: on sikkerhetsanalyse.no a cover of height:295.7mm fits on one A4 page, and 296mm spills a blank page after it.

    Without csspagesize the scale is about 66 %, and the zoom you would need is different (about 1.52). Do not copy the factor across setups. Set the page size explicitly and measure.

    Measure, do not judge by eye

    A PDF viewer zooms to fit the window, so a page that is 30 % too small looks normal on screen. Put a marker at a known position and read its coordinates out of the PDF:

    <div style="position:absolute;left:500px;top:200px">MARK500</div>
    
    pdftotext -bbox out.pdf - | grep MARK500
    # xMin="375…"  means 1 px = 0.75 pt
    # xMin="266…"  means the ~71 % scale is still there

    htmlToPdf runs only in API scripts, so the test goes in a temporary endpoint under #/API/ and is deleted afterwards. See Some docly functions exist only in API scripts.

    Checklist

    • <!-- ChromePDF csspagesize --> and an explicit @page{size:A4;…}.
    • html{zoom:1.4142}, or the factor you measured for your own setup.
    • The page margins are in @page, where they are not scaled.
    • A marker measured with pdftotext -bbox after every change to page size, margins or zoom.

Last reviewed 21 Nov 2026