What is not supported

For individual CSS properties see the property support table, and for wkhtmltopdf’s options see the option mapping.

JavaScript is not executed

<script> elements are skipped.

This rules out the following.

• Building the DOM with JavaScript and then producing a PDF, such as rendering a single-page application as it stands
• Including a chart drawn on the client with something like Chart.js
• Injecting page numbers or headers with JavaScript; use the placeholders instead

Ranges

The input is a single HTML file

Several HTML files cannot be listed and merged into one PDF; there is no equivalent of wkhtmltopdf’s positional arguments. A cover page is given with --cover and a table of contents with --toc.

Merging, splitting, and extracting pages from existing PDFs are out of scope as well.

PDF features

Links written as <a href> become PDF annotations, both for external URLs and for #id targets within the document.

Image and font formats

• Images may be PNG, JPEG, WebP, or SVG only; GIF is not supported
• SVG can only be referenced from <img> and background-image (either a file or a data: URI). An inline <svg> element written directly in the HTML is not drawn, and a warning is printed when one is found
• <text> inside an SVG is drawn only when the svg-text feature is enabled (the fonts available to it are the same as the document’s, and system fonts are never looked up again for the sake of an SVG). <filter> and <image> are not supported (see Images)
• Fonts may be TTF or OTF only; WOFF and WOFF2 are not supported
• Colour fonts are limited to embedded bitmaps (CBDT/CBLC, sbix) and COLR/CPAL v0. COLRv1 (gradients) and OpenType SVG are not supported. For emoji see Fonts
• Even with --grayscale, JPEG and CMYK images and SVG stay in colour

The main CSS limitations

Taken feature by feature, the following are not supported.

• Vertical writing with writing-mode and text-orientation, and right-to-left text through direction (logical properties such as margin-inline are supported only as a fixed mapping for horizontal-tb and LTR)
• Multi-column layout, columns and column-count
• Gradients such as linear-gradient(), and multiple backgrounds
• The relative colour syntax (rgb(from ...)) and color() (color-mix() is supported)
• Animations, transitions, and filter, since the output is static
• position: sticky, display: inline-flex and inline-grid, and subgrid
• ::first-line and ::marker (:is(), :where() and :has() are supported)

In value syntax, calc() and parentheses may be nested up to 32 levels deep. A value deeper than that is invalid and its declaration is ignored. Values are parsed recursively, so without a depth limit an untrusted stylesheet could exhaust the stack.

How whitespace is treated

Only the whitespace CSS Text 3 defines as such — space, tab and newline — is collapsed.   (U+00A0), thin space (U+2009) and the like are ordinary characters that never collapse, and they are drawn at the width the font gives them. Where a line may break follows the UAX #14 line breaking classes: no break is taken on either side of  , narrow no-break space, figure space or word joiner (this holds under word-break: break-all as well).

<wbr> — and U+200B ZERO WIDTH SPACE, which means the same thing — is treated as “a line may break here”. It adds no width and leaves no character in the PDF text layer (text extraction runs the two sides together even with a <wbr> between them).

Within that scope, the known limitations are:

• When text-align: justify stretches a line,   is not one of the gaps it stretches (only ordinary spaces are)
• U+2028 and U+2029 are treated as ordinary whitespace rather than as the forced breaks they are meant to be
• Whitespace that lands at the end of a line is not hung outside the line box

Limitations specific to streaming mode

With --streaming, the total page count, meaning counter(pages) and [topage], and the table of contents, --toc, become unavailable. See Streaming mode for the details.

Looking ahead

Embedding a JavaScript engine remains something to consider if the need arises. Items above that are not deliberate non-goals, such as PDF outlines, may well be supported later.