Skip to main content

Overview

This document provides a concise set of best practices for developing HTML templates and CSS styling for the WeasyPrint rendering engine. Following these guidelines will help improve rendering consistency, template maintainability, and compatibility with the engine.

Although these recommendations are primarily based on WeasyPrint, most of them also apply to PrinceXML. In practice, templates that follow these guidelines work well on both rendering engines. Unless otherwise noted, you can apply these recommendations without worrying about compatibility between WeasyPrint and PrinceXML.

info

The RenderCSS worker currently uses WeasyPrint 69 rather than the latest version. If you are using any older and newer version, it may cause unexpected render result. Please always check the offical documentation of Weasyprint to see if your using properties are supported.

General Principles​

Think like a document, not a web page​

WeasyPrint is a print rendering engine. While it understands HTML and CSS, it does not support every feature available in modern browsers.

When designing templates:

  • Prefer predictability over visual cleverness.
  • Design for printed pages, not responsive scrolling web pages.
  • Use the simplest layout that achieves the design.
  • Always validate templates using realistic production data.