Features

This page is for WeasyPrint v0.42.3. See changelog for older versions.

URLs

WeasyPrint can read normal files, HTTP, FTP and data URIs. It will follow HTTP redirects but more advanced features like cookies and authentication are currently not supported, although a custom url fetcher can help.

HTML

Many HTML elements are implemented in CSS through the HTML5 User-Agent stylesheet.

Some elements need special treatment:

  • The <base> element, if present, determines the base for relative URLs.

  • CSS stylesheets can be embedded in <style> elements or linked by <link rel=stylesheet> elements.

  • <img>, <embed> or <object> elements accept images either in raster formats supported by GdkPixbuf (including PNG, JPEG, GIF, …) or in SVG with CairoSVG. SVG images are not rasterized but rendered as vectors in the PDF output.

HTML presentational hints are not supported by default, but most of them can be supported:

  • by using the --presentational-hints CLI parameter, or

  • by setting the presentational_hints parameter of the HTML.render or HTML.write_* methods to True.

Presentational hints include a wide array of attributes that direct styling in HTML, including font color and size, list attributes like type and start, various table alignment attributes, and others. If the document generated by WeasyPrint is missing some of the features you expect from the HTML, try to enable this option.

PDF

In addition to text, raster and vector graphics, WeasyPrint’s PDF files can contain hyperlinks, bookmarks and attachments.

Hyperlinks will be clickable in PDF viewers that support them. They can be either internal, to another part of the same document (eg. <a href="#pdf">) or external, to an URL. External links are resolved to absolute URLs: <a href="/news/"> on the WeasyPrint website would always point to http://weasyprint.org/news/ in PDF files.

PDF bookmarks are also called outlines and are generally shown in a sidebar. Clicking on an entry scrolls the matching part of the document into view. By default all <h1> to <h6> titles generate bookmarks, but this can be controlled with CSS (see bookmarks.)

Attachments are related files, embedded in the PDF itself. They can be specified through <link rel=attachment> elements to add resources globally or through regular links with <a rel=attachment> to attach a resource that can be saved by clicking on said link. The title attribute can be used as description of the attachment.

Fonts

WeasyPrint can use any font that Pango can find installed on the system. Fonts are automatically embedded in PDF files.

On Windows and macOS, Pango uses the native font-managing libraries. You can use the tools provided by your OS to know which fonts are available. WeasyPrint should support any font format that’s supported by the operating system.

On Linux, Pango uses fontconfig to access fonts. You can list the available fonts thanks to the fc-list command, and know which font is matched by a given pattern thanks to fc-match. Copying a font file into the ~/.local/share/fonts or ~/.fonts directory is generally enough to install a new font. WeasyPrint should support any font format handled by FreeType (any format widely used except WOFF2).

CSS

WeasyPrint supports many of the CSS specifications written by the W3C. You will find in this chapter a comprehensive list of the specifications or drafts with at least one feature implemented in WeasyPrint.

The results of some of the test suites provided by the W3C are also available at test.weasyprint.org. This website uses a tool called WeasySuite that can be useful if you want to implement new features in WeasyPrint.

CSS Level 2 Revision 1

The CSS Level 2 Revision 1 specification, best known as CSS 2.1, is pretty well supported by WeasyPrint. Since version 0.11, it passes the famous Acid2 Test.

The CSS 2.1 features listed here are not supported:

To the best of our knowledge, everything else that applies to the print media is supported. Please report a bug if you find this list incomplete.

Selectors Level 3

With the exceptions noted here, all Selectors Level 3 are supported.

PDF is generally not interactive. The :hover, :active, :focus, :target and :visited pseudo-classes are accepted as valid but never match anything.

CSS Text Module Level 3 / 4

The CSS Text Module Level 3 and CSS Text Module Level 4 are working drafts defining “properties for text manipulation” and covering “line breaking, justification and alignment, white space handling, and text transformation”.

Among their features, some are already included in CSS 2.1, sometimes with missing or different values (text-indent, text-align, letter-spacing, word-spacing, text-transform, white-space).

New properties defined in Level 3 are supported:

  • the overflow-wrap property replacing word-wrap;

  • the full-width value of the text-transform property; and

  • the tab-space property.

Experimental properties controling hyphenation are supported by WeasyPrint:

  • hyphens,

  • hyphenate-character,

  • hyphenate-limit-chars, and

  • hyphenate-limit-zone.

To get automatic hyphenation, you to set it to auto and have the lang HTML attribute set to one of the languages supported by Pyphen.

<!doctype html>
<html lang=en>
<style>
  html { hyphens: auto }
</style>

Automatic hyphenation can be disabled again with the manual value:

html { hyphens: auto }
a[href]::after { content: ' [' attr(href) ']'; hyphens: manual }

The other features provided by CSS Text Module Level 3 are not supported:

  • the line-break and word-break properties;

  • the start, end, match-parent and start end values of the text-align property;

  • the text-align-last and text-justify properties; and

  • the text-indent and hanging-punctuation properties.

The other features provided by CSS Text Module Level 4 are not supported:

  • the text-space-collapse and text-space-trim properties;

  • the text-wrap, wrap-before, wrap-after and wrap-inside properties;

  • the pre-wrap-auto value of the white-space property; and

  • the text-spacing property.

CSS Fonts Module Level 3

The CSS Fonts Module Level 3 is a candidate recommendation describing “how font properties are specified and how font resources are loaded dynamically”.

WeasyPrint supports the font-size, font-stretch, font-style and font-weight properties, coming from CSS 2.1.

WeasyPrint also supports the following font features added in Level 3: - font-kerning, - font-variant-ligatures, - font-variant-position, - font-variant-caps, - font-variant-numeric, - font-variant-east-asian, - font-feature-settings, and - font-language-override.

font-family is supported. The string is given to Pango that tries to find a matching font in a way different from what is defined in the recommendation, but that should not be a problem for common use.

The shorthand font and font-variant properties are supported.

WeasyPrint supports the @font-face rule on Linux and macOS, but does not support it on Windows.

WeasyPrint does not support the @font-feature-values rule and the values of font-variant-alternates other than normal and historical-forms.

The font-variant-caps property is supported but needs the small-caps variant of the font to be installed. WeasyPrint does not simulate missing small-caps fonts.

CSS Paged Media Module Level 3

The CSS Paged Media Module Level 3 is a working draft including features for paged media “describing how:

  • page breaks are created and avoided;

  • the page properties such as size, orientation, margins, border, and padding are specified;

  • headers and footers are established within the page margins;

  • content such as page counters are placed in the headers and footers; and

  • orphans and widows can be controlled.”

All the features of this draft are available, including:

  • the @page rule and the :left, :right, :first and :blank selectors;

  • the page margin boxes;

  • the page-based counters (with known bugs #91, #93, #289);

  • the page size, bleed and marks properties;

  • the named pages.

CSS Generated Content for Paged Media Module

The CSS Generated Content for Paged Media Module (GCPM) is a working draft defining “new properties and values, so that authors may bring new techniques (running headers and footers, footnotes, leaders, bookmarks) to paged media”.

Two features from this module have been implemented in WeasyPrint.

The first feature is PDF bookmarks. Using the experimental bookmark-level and bookmark-level properties, you can add bookmarks that will be available in your PDF reader.

Bookmarks have already been added in the WeasyPrint’s user agent stylesheet, so your generated documents will automatically have bookmarks on headers (from <h1> to <h6>). But for example, if you have only one top-level <h1> and do not wish to include it in the bookmarks, add this in your stylesheet:

h1 { bookmark-level: none }

The second feature is Named strings. You can define strings related to the first or last element of a type present on a page, and display these strings in page borders. This feature is really useful to add the title of the current chapter at the top of the pages of a book for example.

The named strings can embed static strings, counters, tag contents and tag attributes.

@top-center { content: string(chapter); }
h2 { string-set: chapter "Current chapter: " content() }

The other features of GCPM are not implemented:

  • running elements (running() and element());

  • footnotes (float: footnote, footnote-display, footnote counter, ::footnote-call, ::footnote-marker, @footnote rule, footnote-policy);

  • page selectors and page groups (:nth() pseudo-class);

  • leaders (content: leader());

  • cross-references (target-counter(), target-counters() and target-text());

  • bookmark states (bookmark-state).

CSS Color Module Level 3

The CSS Color Module Level 3 is a recommandation defining “CSS properties which allow authors to specify the foreground color and opacity of an element”. Its main goal is to specify how colors are defined, including color keywords and the #rgb, #rrggbb, rgb(), rgba(), hsl(), hsla() syntaxes. Opacity and alpha compositing are also defined in this document.

This recommandation is fully implemented in WeasyPrint, except the deprecated System Colors.

CSS Transforms Module Level 1

The CSS Transforms Module Level 1 working draft “describes a coordinate system within each element is positioned. This coordinate space can be modified with the transform property. Using transform, elements can be translated, rotated and scaled in two or three dimensional space.”

WeasyPrint supports the transform and transform-origin properties, and all the 2D transformations (matrix, rotate, translate(X|Y)?, scale(X|Y)?, skew(X|Y)?).

WeasyPrint does not support the transform-style, perspective, perspective-origin and backface-visibility properties, and all the 3D transformations (matrix3d, rotate(3d|X|Y|Z), translate(3d|Z), scale(3d|Z)).

CSS Backgrounds and Borders Module Level 3

The CSS Backgrounds and Borders Module Level 3 is a candidate recommandation defining properties dealing “with the decoration of the border area and with the background of the content, padding and border areas”.

The border part of this module is supported, as it is already included in the the CSS 2.1 specification.

WeasyPrint supports the background part of this module (allowing multiple background layers per box), including the background, background-color, background-image, background-repeat, background-attachment, background-position, background-clip, background-origin and background-size properties.

WeasyPrint also supports the rounded corners part of this module, including the border-radius property.

WeasyPrint does not support the border images part of this module, including the border-image, border-image-source, border-image-slice, border-image-width, border-image-outset and border-image-repeat properties.

WeasyPrint does not support the box shadow part of this module, including the box-shadow property. This feature has been implemented in a git branch that is not released, as it relies on raster implementation of shadows.

CSS Image Values and Replaced Content Module Level 3 / 4

The Image Values and Replaced Content Module Level 3 is a candidate recommandation introducing “additional ways of representing 2D images, for example as a list of URIs denoting fallbacks, or as a gradient”, defining “several properties for manipulating raster images and for sizing or positioning replaced elements” and “generic sizing algorithm for replaced elements”.

The Image Values and Replaced Content Module Level 4 is a working draft on the same subject.

The linear-gradient(), radial-gradient() and repeating-radial-gradient() properties are supported as background images.

The the url() notation is supported, but the image() notation is not supported for background images.

The from-image and snap values of the image-resolution property are not supported, but the resolution value is supported.

The image-rendering property is supported.

The image-orientation, object-fit and object-position are not supported.

CSS Basic User Interface Module Level 3

The CSS Basic User Interface Module Level 3 also known as CSS3 UI is a candidate recommandation describing “CSS properties which enable authors to style user interface related properties and values.”

Only one new property defined in this document is implemented in WeasyPrint: the box-sizing property.

Some of the properties do not apply for WeasyPrint: cursor, resize, caret-color, nav-(up|right|down|left).

The other properties are not implemented: outline-offset and text-overflow.

CSS Values and Units Module Level 3

The CSS Values and Units Module Level 3 defines various units and keywords used in “value definition field of each CSS property”.

The initial and inherit CSS-wide keywords are supported, but the unset keyword is not supported.

Quoted strings, URLs and numeric data types are supported.

Font-related lengths (em, ex, ch, rem), absolute lengths (cm, mm, q, in, pt, pc, px), angles (rad, grad, turn, deg), resolutions (dpi, dpcm, dppx) are supported.

The attr() functional notation is allowed in the content and string-set properties.

Viewport-percentage lengths (vw, vh, vmin, vmax) are not supported.

CSS Multi-column Layout Module

The CSS Multi-column Layout Module “describes multi-column layouts in CSS, a style sheet language for the web. Using functionality described in the specification, content can be flowed into multiple columns with a gap and a rule between them.”

Simple multi-column layouts are supported in WeasyPrint. Features such as constrained height, spanning columns or column breaks are not supported. Pagination and overflow are not seriously tested.

The column-width and column-count properties, and the columns shorthand property are supported.

The column-gap, column-rule-color, column-rule-style and column-rule-width properties, and the column-rule shorthand property are supported.

The break-before, break-after and break-inside properties are not supported.

The column-span property is not supported.

The column-fill property is supported, with a column balancing algorithm that should be efficient with simple cases.