Common Issues in HTML-to-PDF Printing (and How to Fix Them)

Table of Contents

• 1. Page Break Errors
• 2. Missing Body Margins
• 3. Inconsistent Font Sizes
• 4. Poor Table Formatting
• 5. Pagination Problems

Common Issue 1: Page Break Errors

One of the most common and frustrating challenges when exporting HTML content to PDF is dealing with page break errors. These errors typically occur when large elements such as tables, paragraphs, or images are broken apart by the PDF rendering engine. On a website, scrolling provides a seamless flow of information, but in a PDF the content is forced into fixed, discrete pages. Without explicit instructions, the browser or rendering tool decides where to cut the content, often at awkward or illogical places. This can create professional and usability issues—for example, an invoice where a single table row is split between two pages, or a multi-step instruction guide where a heading lands at the bottom of one page while the related text begins on the next.

Understanding how browsers and PDF converters handle pagination is essential. Most engines attempt to fit as much as possible on one page before moving the overflow to the next. However, the process is not always intelligent enough to recognize “keep together” elements such as table rows, image captions, or lists. Developers need to intervene using CSS print rules like page-break-before, page-break-after, or page-break-inside. Among these, page-break-inside: avoid is especially useful for tables because it prevents rows or entire table bodies from being split in half.

Let’s consider an example: a sales invoice table with ten rows. Without any page break handling, the first seven rows might appear on one page, while the last three overflow onto the next. In some cases, a single row might even be cut in half: the top border on one page, and the bottom border on the next. This not only looks unprofessional but also makes the data harder to understand. By applying page-break-inside: avoid; to the table (or to the rows themselves), you ensure that each row is kept together as a block. If the entire row doesn’t fit on the current page, the rendering engine pushes the whole row onto the next page.

table {
page-break-inside: avoid;
}

Using the rule above is a best practice for invoices, schedules, timetables, or any structured data that depends on visual alignment. But page break handling doesn’t stop there—there are other situations where explicit control is critical. For example, chapter-based documents (like ebooks or research papers) often require that every chapter begins on a new page. To achieve this, developers use a dedicated “page-break” class with page-break-before: always. Similarly, to prevent page breaks after a heading but before its associated content, page-break-after: avoid can be applied.

Another important detail is how different browsers and PDF rendering libraries interpret page break rules. Chrome’s print-to-PDF feature and libraries like wkhtmltopdf or Puppeteer follow CSS print specifications, but subtle differences exist. For instance, while Chrome recognizes break-inside: avoid (the modern replacement for page-break-inside), older libraries may only respect the legacy property. This means developers should often include both for maximum compatibility:

table {
  break-inside: avoid;          /* Modern CSS */
  page-break-inside: avoid;     /* Legacy fallback */
}

Another subtlety is nested content. A parent container might respect page break rules, but its children may still break if not explicitly controlled. For example, a multi-column flex layout might split halfway if you don’t define break behavior for both the row container and its columns. This is especially critical in responsive layouts, where content reflows depending on screen width. When exporting to PDF, this dynamic behavior can lead to unpredictable splits. The safest solution is to assign break rules at every critical container level: sections, rows, and individual blocks of content.

From a user-experience perspective, page break errors damage readability and trust. Imagine handing a client a PDF contract where the signature line is cut in half between two pages—it instantly makes the document look sloppy. In academic or technical settings, page breaks that interrupt tables, formulas, or code snippets can render the material unusable. These issues may seem minor in development but have a large impact on end-users who expect print-ready quality.

There are also performance considerations. Complex documents with heavy use of page-break rules may take longer to render into PDF. Each break rule forces the rendering engine to calculate potential reflows and adjust layouts accordingly. While this overhead is usually minimal for small documents, it can be significant for large reports with hundreds of tables or images. A balanced approach is key: only apply break rules where absolutely necessary, and test thoroughly across multiple browsers and PDF tools.

A good strategy for handling page breaks includes:

• Identify critical sections (tables, charts, chapter headings) that must not be split.
• Apply page-break-inside: avoid to those sections or their parent containers.
• Use page-break-before: always or page-break-after: always for elements that require isolation (e.g., chapters, cover pages, or appendices).
• Test across different browsers and PDF generators to ensure consistency.
• Combine legacy (page-break-*) and modern (break-*) properties for maximum support.

In conclusion, page break errors are one of the most frequent sources of frustration in HTML-to-PDF workflows. While browsers attempt to handle pagination automatically, the results rarely meet professional standards. Developers must take control with CSS rules, testing, and deliberate structure to produce documents that look clean and reliable in print. A single property like page-break-inside: avoid may seem simple, but it can dramatically improve the readability and polish of your exported PDFs. By mastering these techniques, you transform awkward, broken layouts into documents that are polished, professional, and user-friendly.

Common Issue 2: Missing Body Margins

When exporting web content to PDF, one of the most overlooked issues is the lack of proper margins. Many developers naturally assume that margins defined on the <body> tag will carry over into print. On a webpage, this assumption works fine because browsers respect body margins when displaying content on screen. However, most PDF rendering engines—including browser-based ones like Chrome’s "Print to PDF" and libraries such as Puppeteer or wkhtmltopdf—ignore these body margins during printing. The result is a document where text, images, or tables are flush with the very edges of the page. This creates a cluttered, unprofessional appearance and can even cause important content to be cut off by the printer’s non-printable areas.

Printers have physical constraints. Most cannot print edge-to-edge without special configurations (this is usually reserved for professional printing services using bleed settings). Consumer and office printers leave a margin of at least 0.25–0.5 inches around the paper edges. If your HTML-to-PDF export does not respect these constraints, the rendered document risks losing portions of headers, footers, or side content. This is why CSS provides the @page rule: it explicitly defines the print margins for the entire document, ensuring that every page maintains consistent whitespace regardless of how content is structured inside.

@page {
  margin: 1in;
  size: A4;  /* Explicit page size */
}

The rule above defines a uniform 1-inch margin around every page. This is the default standard for professional reports, academic papers, and legal documents. A one-inch margin provides enough whitespace for readability and ensures that content remains safe from printer cutoff zones. While you can customize these margins, it’s important to follow established conventions unless you have a specific design goal.

Developers often fall into the trap of thinking body margins are sufficient. Let’s take an example. Imagine you build a company report with the following CSS:

body {
  margin: 40px;
}

On screen, the report looks fine—the text sits comfortably within the viewport, and the design appears polished. But when exported to PDF, the body margins are ignored, and the content hugs the page edges. This creates an immediate readability issue: the eye has no whitespace buffer, and the page looks crowded. Furthermore, if this PDF is printed, the printer may crop off content, making the document incomplete or difficult to use.

To fix this, always use @page. Not only does it ensure proper margins, but it also lets you define them differently for various use cases.

For instance, you can create wide top margins for headers, smaller side margins for compact tables, or larger bottom margins to leave space for signatures. Here's a practical example with asymmetric margins:

@page {
  margin-top: 1.5in;
  margin-right: 1in;
  margin-bottom: 1in;
  margin-left: 1.25in;
}

This layout might be used for formal reports where the top margin leaves space for a company letterhead or watermark, while the slightly larger left margin accommodates binding or hole punching. Unlike body margins, @page guarantees these values are respected during printing and PDF generation.

Another key point is consistency. If margins are not defined globally, developers might try to fake them by padding inner containers or using wrapper divs with spacing. While this can work on screen, it’s fragile in print. Imagine a 50-page report where one page accidentally renders without padding—suddenly, that single page breaks the uniformity of the entire document. @page eliminates this fragility by applying margins at the page level, not the element level.

There are also usability and accessibility implications. Whitespace around content is not just about aesthetics—it dramatically affects readability. Dense text that runs edge-to-edge is harder to scan, especially in long documents. Proper margins give the eye room to rest, helping readers process information more efficiently. In professional contexts (such as legal contracts or academic theses), missing margins can make a document look amateurish, undermining the credibility of the content.

Advanced use cases of @page include defining different margin rules for the first page, left pages, and right pages. For example:

@page:first {
  margin-top: 2in; /* Extra space for a title page */
}

@page:left {
  margin-left: 1.5in; /* For binding */
}

@page:right {
  margin-right: 1.25in; /* Balanced layout */
}

This approach is common in book publishing or multi-page reports where odd and even pages need slightly different layouts. It’s also critical in documents destined for professional printing, where binding eats into the inner margin. Without proper margin handling, text may appear too close to the spine, making it difficult to read.

Finally, remember that not all PDF tools support advanced @page selectors. While modern browsers like Chrome handle them well, some older libraries may only apply uniform margins. For maximum compatibility, test your documents in the exact environment where they’ll be used. If a client will print from Chrome, test with Chrome. If you’re automating PDF generation with wkhtmltopdf, verify that your @page rules are respected there too. This testing step is crucial to avoid surprises.

In summary, missing body margins is one of the most common yet easily fixable mistakes in HTML-to-PDF workflows. Always use @page to define print-safe margins. Stick to standard measurements like 1 inch unless your design demands otherwise. Consider asymmetric or advanced margin settings for professional layouts, and test across different rendering engines. By mastering margins, you guarantee that your documents not only look professional but also print reliably on any device.

Common Issue 3: Inconsistent Font Sizes

Fonts play a critical role in the readability and professionalism of printed documents. On the web, users can zoom in, change display settings, or view text on high-resolution screens, which makes even small or decorative fonts appear legible. But in print, there is no such flexibility. Tiny fonts that might look acceptable on a 1080p or 4K monitor can become nearly invisible when rendered onto paper. Similarly, lightweight or decorative typefaces may look stylish on screen but lose sharpness and clarity when printed, especially if the printer is monochrome or low-resolution. This is why font choice and consistent sizing are essential for HTML-to-PDF exports.

A common mistake developers make is relying on pixel-based font sizing (px) when designing layouts. While this works for screens, it does not translate well to print. Printers and PDF engines expect physical units like pt (points), cm (centimeters), or in (inches). A 12px font, which might be legible on screen, is significantly smaller than a 12pt font on paper. Professional print documents—such as resumes, reports, and contracts—typically use a standard size of 10pt to 12pt for body text. Anything smaller than 9pt risks being difficult to read, while anything larger than 14pt for body text looks unbalanced and wastes space.

body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif;
  font-size: 12pt;
  line-height: 1.5;  /* Better readability */
}

The rule above demonstrates best practices: selecting a professional, widely available font (Arial) and specifying size in points (pt). Points are the traditional unit in typography, where 1pt equals 1/72 of an inch. This ensures your text renders consistently across different printers and PDF readers. By contrast, pixels are relative to screen resolution, making them unreliable for print workflows. Always use pt for predictable results in print.

Font choice is another frequent source of inconsistency. Many web fonts are optimized for digital screens, not for paper. Thin, script, or ornamental fonts often render poorly when converted to PDF, especially if the printer only supports grayscale. For example, a lightweight Google Font might appear elegant in color on screen, but when reduced to black-and-white output, it becomes faint and difficult to distinguish. On the other hand, fonts like Arial, Times New Roman, Helvetica, and Georgia are considered “print-safe” because they are well-supported, highly legible, and designed with professional use cases in mind. These fonts also benefit from being system defaults on most operating systems, reducing the risk of fallback rendering.

Another pitfall occurs when developers use inconsistent font sizes throughout a document. A heading might be set in pixels, a table in percentages, and the body text in points. While this might appear fine in a browser, the PDF export will highlight these discrepancies. Headings could appear disproportionately large, tables may shrink to unreadable sizes, and the overall document will feel unbalanced. Consistency is key: choose one unit system (preferably points) and apply it throughout all sections of the document—headings, paragraphs, captions, tables, and footnotes. For example:

h1 { font-size: 18pt; }
h2 { font-size: 16pt; }
p  { font-size: 12pt; }
small { font-size: 10pt; }

This typographic hierarchy maintains clarity and professionalism. Headings stand out, body text is comfortable to read, and smaller annotations are still legible. Avoid using sizes below 9pt unless absolutely necessary, such as for disclaimers or footnotes. Remember: while screens allow pinch-zooming, printed pages do not. Once text is too small, it is permanently hard to read.

Inconsistent font scaling can also arise in responsive designs. On a webpage, media queries adjust text sizes for small screens versus desktops. But in a PDF export, these queries may not behave as intended. For example, if the PDF rendering engine treats the viewport as wide, it may apply desktop styles, making headings appear massive in print. Conversely, if it assumes a narrow viewport, your entire document could print with tiny, mobile-sized text. To solve this, always include a dedicated @media print section in your CSS where you define explicit font sizes for printed output. Example:

@media print {
  body { font-size: 12pt; }
  h1 { font-size: 18pt; }
  h2 { font-size: 16pt; }
}

This ensures that regardless of how your layout adapts on screen, the PDF version maintains a consistent, professional typographic structure. It separates your on-screen design from your print design, which is a crucial step in producing polished documents.

Beyond readability, font consistency affects credibility. Imagine a business proposal where some sections use Times New Roman at 11pt, others use Calibri at 10px, and headings vary wildly in size. Even if the content is excellent, the reader subconsciously perceives the document as less professional because of its lack of typographic discipline. In contrast, a document with uniform, carefully chosen font sizes conveys reliability and attention to detail. This is particularly important in academic, legal, and corporate contexts where first impressions matter.

Another advanced consideration is how fonts are embedded in the PDF. Some rendering engines automatically embed fonts, while others rely on system defaults. If a font is missing, the PDF reader substitutes it with another, which can alter spacing and cause layout shifts. To prevent this, stick with system-safe fonts or ensure your rendering tool supports font embedding. For example, Google Chrome’s PDF exporter embeds fonts reliably, but wkhtmltopdf may require additional flags or configurations.

In summary, inconsistent font sizes are one of the most visible errors in HTML-to-PDF workflows. They compromise readability, aesthetic balance, and professional credibility. Always use pt units for print, establish a clear typographic hierarchy, and select fonts that are proven to be print-safe. Test your document across different rendering engines and devices to confirm that text appears consistent in every case. By paying attention to typography, you elevate your PDFs from “good enough” to truly professional.

Common Issue 4: Poor Table Formatting

Tables are one of the most common elements exported from HTML to PDF. They appear in invoices, financial reports, schedules, product catalogs, and academic documents. Unfortunately, poorly formatted tables are also one of the most frequent issues in print output. Without clear styling, tables collapse into dense, unreadable blocks of text, losing the visual separation that helps readers scan and understand the data. Borders, spacing, and consistent alignment are essential for ensuring that tables remain clear and professional when exported to PDF.

Many developers underestimate how different a table can look when printed compared to how it appears on screen. On a browser, background shading, hover effects, and subtle lines may give enough visual cues to separate rows and columns. But in a printed PDF—especially on a monochrome printer—those subtle styles vanish. Light gray dividers may not be visible, and hover states obviously don’t apply. What’s left is often a page of misaligned text that looks messy and unprofessional. This is why explicit, print-friendly styling is so important for tables.

table {
  width: 100%;
  border-collapse: collapse;
  page-break-inside: avoid;
}

table, th, td {
  border: 1px solid black;
}

The above CSS snippet demonstrates the foundation of good table formatting. Applying a 1px solid black border to table, th, and td ensures every cell is clearly separated. Using border-collapse: collapse; eliminates the default double-line effect between adjacent cells, giving the table a clean and unified appearance. Even in black-and-white print, this ensures the structure of the data is preserved and easy to follow.

Another frequent issue is the lack of padding inside table cells. By default, text often sits directly against cell borders, which makes the content cramped and harder to read. Adding padding creates breathing room, improving readability and professionalism. For example:

th, td {
  padding: 6pt 8pt;
  text-align: left;
}

Padding not only makes tables more legible but also helps balance the spacing across the document. Without it, even well-bordered tables may appear amateurish. The text-align property is also critical: left-alignment works best for text, while right-alignment is standard for numbers, ensuring decimals and currency symbols line up neatly. This small detail can make financial documents appear significantly more professional.

Another common problem is inconsistency in table styling across a single document. One table might use borders, another might rely on shading, and yet another might have no formatting at all. This inconsistency disrupts the flow and credibility of the PDF. A professional approach is to define a reusable table style in your CSS and apply it consistently throughout. For example:

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

.table-print th,
.table-print td {
  border: 1px solid black;
  padding: 8pt;
}

By creating a .table-print class, you ensure every table shares the same formatting. This consistency improves readability and makes your document look polished. It also reduces the risk of some tables accidentally printing without borders or padding due to missing inline styles.

Color usage is another challenge. Web designers often rely on soft background colors (like light gray or pale blue) to differentiate header rows or alternating rows. While this works on screen, these subtle colors may not appear at all in grayscale printing. Instead, it’s safer to use bold borders, shading with high-contrast values (like black on white), or even patterns if absolutely needed. A common professional solution is to use slightly darker shading for header rows combined with bold text, ensuring they stand out regardless of whether the document is printed in color or black and white.

Tables with excessive complexity also cause problems in PDF exports. Nested tables, merged cells, or overly wide columns may render unpredictably, causing misalignment or cutoff text. While HTML allows this flexibility, print engines are less forgiving. To prevent this, always test your table layouts by exporting and reviewing them in PDF format. Adjust column widths manually when needed, and avoid deep nesting unless absolutely necessary. Simple, consistent structures print best.

Long tables introduce a separate issue: page breaks. Without explicit control, a table may split awkwardly across two pages, leaving the header row separated from its data. To fix this, use print-specific CSS:

thead { display: table-header-group; }
tfoot { display: table-footer-group; }
table { page-break-inside: avoid; }

This ensures that header rows repeat on each printed page and that tables do not break in the middle of important rows. These small adjustments greatly improve the professionalism of reports and invoices.

Poorly formatted tables don’t just affect readability; they also affect credibility. A business proposal with messy tables looks careless. A financial report without clear borders may be misinterpreted. Even a restaurant menu that lacks proper alignment can confuse customers. On the other hand, well-structured tables communicate reliability, precision, and professionalism. They show that the creator paid attention to detail—a quality that reflects positively on the organization or individual behind the document.

In summary, poor table formatting is one of the most common but easily fixable problems in HTML-to-PDF workflows. Always include borders, use padding for readability, align content consistently, and test your tables in print. Avoid reliance on color alone for structure, and keep layouts simple. With these practices, your tables will transform from confusing blocks of text into clear, professional, and reliable data presentations.

Common Issue 5: Pagination Problems

Pagination is one of the trickiest aspects of exporting HTML to PDF. Unlike scrolling web pages, printed pages have fixed boundaries. If pagination is ignored, content may be cut off, leave awkward blank spaces, or break in the middle of critical elements like tables, images, or chapters. This disrupts the reading flow and makes the final document appear unprofessional. Developers often overlook the importance of inserting manual breaks or defining pagination rules, assuming the browser or PDF engine will handle it automatically. Unfortunately, that assumption often leads to serious layout issues.

By default, browsers attempt to paginate content logically, but their algorithms are designed for general cases, not for precision publishing. For example, a browser might break a table across two pages, leaving column headers on one page and the rest of the data on the next. Or it might split an image in half across pages, producing an unusable result. These errors happen because the rendering engine does not understand the semantic importance of certain sections. That responsibility falls on the developer to provide explicit rules for controlling page breaks.

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

The snippet above shows a simple but effective solution: defining a .page-break class that enforces a manual page break. When this class is applied to a <div> or other block-level element, the PDF renderer ensures that the next section begins on a fresh page. This approach is especially useful for structured documents like invoices, reports, books, or academic papers, where different sections must remain visually separate.

There are two main CSS properties used to manage pagination: page-break-before and page-break-after. The first forces a new page before the element, while the second forces one after. For example, chapters in an ebook or report may use page-break-before: always to start on new pages, while appendices may use page-break-after: always to create clear separation. Together, they give developers precise control over where one page ends and another begins.

A common mistake is overusing page breaks. Adding too many forced breaks can result in wasted whitespace or even blank pages. For instance, if a forced break appears too close to the bottom of an existing page, the PDF may insert an entire blank page before the break. This is especially frustrating when printing multi-page reports, as it makes the document look sloppy and artificially inflated. To avoid this, breaks should be used strategically—only where logical separation is needed, such as between major sections, not after every element.

Long tables and images require special handling. A table might stretch across several pages, but if no rules are applied, rows may split unpredictably, leaving partial rows on one page and the remainder on the next. To prevent this, combine page-break-inside: avoid; with pagination rules. Similarly, for large images or charts, it is better to place them inside a container with .page-break before and after, ensuring the image stays whole on a single page rather than being cut in half.

Another overlooked aspect is repeating elements such as headers and footers. In professional documents, section titles or table headers often need to appear consistently across multiple pages. Without proper pagination rules, these elements may disappear after the first page, leaving readers confused. By pairing @page rules with CSS for headers and footers, developers can enforce consistent repetition. For example:

With this setup, table headers automatically repeat at the top of each page where the table continues, improving readability. This is a direct solution to pagination-related problems that occur when long data sets spill across pages.

Page numbering is another critical part of pagination. A PDF that runs dozens of pages without numbers becomes frustrating to navigate. Using @page with counters, developers can insert "Page X of Y" at the bottom of every page. This provides context for readers, especially in official documents like contracts or manuals. It also adds professionalism and reduces the risk of misinterpretation if the document is printed and physically shuffled.

It’s also worth mentioning that different browsers handle pagination rules differently. For instance, Chrome’s print-to-PDF engine might interpret a page-break-before rule slightly differently from Firefox’s. This inconsistency means thorough testing across multiple browsers is necessary. If a PDF will be widely distributed or archived, testing ensures that the layout holds up regardless of which rendering engine was used.

Beyond technical accuracy, pagination has psychological effects on the reader. Well-timed breaks improve pacing and comprehension. For example, starting a new chapter or report section on a fresh page signals a shift in focus and gives the reader a natural pause. Conversely, clumsy breaks—such as splitting a sentence across pages—create distraction and frustration. In professional contexts, such as client invoices or business proposals, these small details can influence how seriously the document is taken.

In conclusion, pagination problems are common but entirely avoidable. Developers must take control of how content flows between pages rather than relying on default browser behavior. Use .page-break classes for manual control, combine them with page-break-before and page-break-after, prevent awkward splits with page-break-inside: avoid, and enhance usability with repeating headers, footers, and page numbers. When pagination is handled correctly, documents not only look professional but also guide the reader smoothly from start to finish.