API Reference
=============

.. currentmodule:: weasyprint


This page is for WeasyPrint |version|. See :doc:`changelog </changelog>` for
older versions.


API Stability
-------------

Everything described here is considered “public”: this is what you can rely
on. We will try to maintain backward-compatibility, and we really often do, but
there is no hard promise.

Anything else should not be used outside of WeasyPrint itself. We reserve
the right to change it or remove it at any point. Use it at your own risk,
or have dependency to a specific WeasyPrint version.


Versioning
----------

WeasyPrint provides frequent major releases, and minor releases with only bug
fixes. Versioning is close to what many browsers do, including Firefox and
Chrome: big major numbers, small minor numbers.

Even if each version does not break the API, each version does break the way
documents are rendered, which is what really matters at the end. Providing
minor versions would give the illusion that developers can just update
WeasyPrint without checking that everything works.

Unfortunately, we have the same problem as the other browsers: when a new
version is released, most of the user's websites are rendered exactly the same,
but a small part is not. And the only ways to know that, for web developers,
are to read the changelog and to check that their pages are correctly rendered.

More about this choice can be found in
issue `#900`_.

.. _#900: https://github.com/Kozea/WeasyPrint/issues/900


Command-line API
----------------

.. autofunction:: weasyprint.__main__.main(argv=sys.argv)


Python API
----------

.. autoclass:: HTML(input, **kwargs)
    :members:
.. autoclass:: CSS(input, **kwargs)
.. autoclass:: Attachment(input, **kwargs)
.. autofunction:: default_url_fetcher
.. autodata:: DEFAULT_OPTIONS

.. module:: weasyprint.document
.. autoclass:: Document
    :members:
.. autoclass:: DocumentMetadata()
    :members:
.. autoclass:: Page()
    :members:
    :exclude-members: paint

.. module:: weasyprint.text.fonts
.. autoclass:: FontConfiguration()

.. module:: weasyprint.css.counters
.. autoclass:: CounterStyle()


Supported Features
------------------


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 :ref:`URL fetcher
<URL Fetchers>` can help.

.. _data URIs: https://en.wikipedia.org/wiki/Data_URI_scheme


HTML
~~~~

Supported HTML Tags
+++++++++++++++++++

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 Pillow_ (including PNG, JPEG, GIF, ...)
  or in SVG. 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.

.. _User-Agent stylesheet: https://github.com/Kozea/WeasyPrint/blob/main/weasyprint/css/html5_ua.css
.. _presentational hints: https://www.w3.org/TR/html5/rendering.html#presentational-hints
.. _Pillow: https://python-pillow.org/

Stylesheet Origins
++++++++++++++++++

HTML documents are rendered with stylesheets from three *origins*:

* The HTML5 `user agent stylesheet`_ (defines the default appearance
  of HTML elements);
* Author stylesheets embedded in the document in ``<style>`` elements
  or linked by ``<link rel=stylesheet>`` elements;
* User stylesheets provided in the API.

Keep in mind that *user* stylesheets have a lower priority than *author*
stylesheets in the cascade_, unless you use `!important`_ in declarations
to raise their priority.

.. _user agent stylesheet: https://github.com/Kozea/WeasyPrint/blob/main/weasyprint/css/html5_ua.css
.. _cascade: https://www.w3.org/TR/CSS21/cascade.html#cascading-order
.. _!important: https://www.w3.org/TR/CSS21/cascade.html#important-rules


PDF
~~~

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

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="/blog-articles/">`` on the CourtBouillon website
would always point to https://www.courtbouillon.org/blog-articles/ 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 `PDF 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.

Generated documents can also include PDF forms, using the ``appearance: auto``
CSS property or the ``--pdf-forms`` CLI option.

The generation of PDF/A and PDF/UA documents is supported. However, the
generated documents are not guaranteed to be valid, and users have the
responsibility to check that they follow the rules listed by the related
specifications.


Fonts
~~~~~

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

Pango always uses fontconfig to access fonts, even on Windows and macOS. 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`` directory is generally enough to install a
new font. WeasyPrint should support the major font formats handled by Harfbuzz.


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 specifications: https://www.w3.org/Style/CSS/current-work
.. _test.weasyprint.org: http://test.weasyprint.org/
.. _WeasySuite: https://github.com/Kozea/WeasySuite

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:

* The `::first-line`_ pseudo-element.
* On tables: `visibility: collapse`_.
* Minimum and maximum height_ on table-related boxes.
* Minimum and maximum width_ and height_ on page-margin boxes.
* Conforming `font matching algorithm`_. Currently ``font-family``
  is passed as-is to Pango.
* Right-to-left or `bi-directional text`_.
* `System colors`_ and `system fonts`_. The former are deprecated in `CSS Color
  Module Level 3`_.

.. _CSS Level 2 Revision 1: https://www.w3.org/TR/CSS21/
.. _Acid2 Test: https://www.webstandards.org/files/acid2/test.html
.. _::first-line: https://www.w3.org/TR/CSS21/selector.html#first-line-pseudo
.. _empty-cells: https://www.w3.org/TR/CSS21/tables.html#empty-cells
.. _visibility\: collapse: https://www.w3.org/TR/CSS21/tables.html#dynamic-effects
.. _width: https://www.w3.org/TR/CSS21/visudet.html#min-max-widths
.. _height: https://www.w3.org/TR/CSS21/visudet.html#min-max-heights
.. _font matching algorithm: https://www.w3.org/TR/CSS21/fonts.html#algorithm
.. _Bi-directional text: https://www.w3.org/TR/CSS21/visuren.html#direction
.. _System colors: https://www.w3.org/TR/CSS21/ui.html#system-colors
.. _system fonts: https://www.w3.org/TR/CSS21/fonts.html#propdef-font

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 / 4
+++++++++++++++++++++

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.

Everything in `Selectors Level 4`_ is supported, except:

- ``:dir``,
- input pseudo-classes (``:valid``, ``:invalid``…),
- column selector (``||``, ``:nth-col()``, ``:nth-last-col()``).

.. _Selectors Level 3: https://www.w3.org/TR/selectors-3/
.. _Selectors Level 4: https://www.w3.org/TR/selectors-4/

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 ``break-all`` value of the ``word-break`` property (see `#1153`_);
- the ``full-width`` value of the ``text-transform`` property; and
- the ``start``, ``end`` and ``justify-all`` values of the ``text-align`` property;
- the ``text-align-last`` and ``text-justify`` properties; and
- the ``tab-size`` property.

Properties controlling 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`_.

.. code-block:: html

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

Automatic hyphenation can be disabled again with the ``manual`` value:

.. code-block:: css

    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`` property;
- the ``match-parent`` value of the ``text-align`` property;
- 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 ``text-align`` property with an alignment character;
- the ``pre-wrap-auto`` value of the ``white-space`` property; and
- the ``text-spacing`` property.

.. _#1153: https://github.com/Kozea/WeasyPrint/issues/1153
.. _supported by Pyphen: https://github.com/Kozea/Pyphen/tree/main/pyphen/dictionaries
.. _hyphenation: https://www.w3.org/TR/css-text-3/#hyphenation
.. _CSS Text Module Level 3: https://www.w3.org/TR/css-text-3/
.. _CSS Text Module Level 4: https://www.w3.org/TR/css-text-4/

CSS Fonts Module Level 3 / 4
++++++++++++++++++++++++++++

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.

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

From `CSS Fonts Module Level 4`_ we only support the
``font-variation-settings`` property enabling specific font variations.

.. _CSS Fonts Module Level 3: https://www.w3.org/TR/css-fonts-3/
.. _CSS Fonts Module Level 4: https://www.w3.org/TR/css-fonts-4/


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 limitations  `#93`_);
- the page ``size``, ``bleed`` and ``marks`` properties;
- the named pages.

.. _CSS Paged Media Module Level 3: https://drafts.csswg.org/css-page-3/
.. _#93: https://github.com/Kozea/WeasyPrint/issues/93

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, page selection) to paged media".

`Page selectors`_ are supported by WeasyPrint. You can select pages according
to their position in the document:

.. code-block:: css

    @page :nth(3) { background: red } /* Third page */
    @page :nth(2n+1) { background: green } /* Odd pages */
    @page :nth(1 of chapter) { background: blue } /* First pages of chapters */

You can also use `running elements`_ to put HTML boxes into the page margins
(but the ``start`` parameter of ``element()`` is not supported).

Footnotes_ are supported. You can put a box in the footnote area using the
``float: footnote`` property. Footnote markers and footnote calls can be
defined using the ``::footnote-marker`` and ``::footnote-call``
pseudo-elements. You can also change the way footnotes are displayed using the
``footnote-display`` property (``compact`` is not supported), and influence
over the rendering of difficult pages with ``footnote-policy``.

.. _CSS Generated Content for Paged Media Module: https://www.w3.org/TR/css-gcpm-3/
.. _Page selectors: https://www.w3.org/TR/css-gcpm-3/#document-page-selectors
.. _running elements: https://www.w3.org/TR/css-gcpm-3/#running-elements
.. _Footnotes: https://www.w3.org/TR/css-gcpm-3/#footnotes

CSS Generated Content Module Level 3
++++++++++++++++++++++++++++++++++++

The `CSS Generated Content Module Level 3`_ is a working draft helping "authors
[who] sometimes want user agents to render content that does not come from the
document tree. One familiar example of this is numbered headings
[…]. Similarly, authors may want the user agent to insert the word "Figure"
before the caption of a figure […], or replacing elements with images or other
multimedia content."

`Named strings`_ are supported by WeasyPrint. 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, cross-references, tag
contents and tag attributes.

.. code-block:: css

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

`Cross-references`_ retrieve counter or content values from targets (anchors or
identifiers) in the current document:

.. code-block:: css

    a::after { content: ", on page " target-counter(attr(href), page) }
    a::after { content: ", see " target-text(attr(href)) }

In particular, ``target-counter()`` and ``target-text()`` are useful when it
comes to tables of contents (see `an example`_).

You can also control `PDF bookmarks`_ with WeasyPrint. Using the
``bookmark-level``, ``bookmark-label`` and ``bookmark-state`` 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:

.. code-block:: css

    h1 { bookmark-level: none }

`Leaders`_ are also supported:

.. code-block:: css

    li a::after {
        content: ' ' leader(dotted) ' ' target-counter(attr(href), page);
    }

The other features of this module are **not** implemented:

- quotes (``content: *-quote``);

.. _CSS Generated Content Module Level 3: https://www.w3.org/TR/css-content-3/
.. _Quotes: https://www.w3.org/TR/css-content-3/#quotes
.. _Named strings: https://www.w3.org/TR/css-content-3/#named-strings
.. _Cross-references: https://www.w3.org/TR/css-content-3/#cross-references
.. _an example: https://github.com/Kozea/WeasyPrint/pull/652#issuecomment-403276559
.. _PDF bookmarks: https://www.w3.org/TR/css-content-3/#bookmark-generation
.. _user agent stylesheet: https://github.com/Kozea/WeasyPrint/blob/main/weasyprint/css/html5_ua.css
.. _Leaders: https://www.w3.org/TR/css-content-3/#leaders

CSS Color Module Level 3
++++++++++++++++++++++++

The `CSS Color Module Level 3`_ is a recommendation 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 recommendation is fully implemented in WeasyPrint, except the deprecated
System Colors.

.. _CSS Color Module Level 3: https://www.w3.org/TR/css-color-3/

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``,
``translateX``, ``translateY``, ``scale``, ``scaleX``, ``scaleY``, ``skew``,
``skewX``, ``skewY``).

WeasyPrint does **not** support the ``transform-style``, ``perspective``,
``perspective-origin`` and ``backface-visibility`` properties, and all the 3D
transformations (``matrix3d``, ``rotate3d``, ``rotateX``, ``rotateY``,
``rotateZ``, ``translate3d``, ``translateZ``, ``scale3d``, ``scaleZ``).

.. _CSS Transforms Module Level 1: https://drafts.csswg.org/css-transforms-1/

CSS Backgrounds and Borders Module Level 3
++++++++++++++++++++++++++++++++++++++++++

The `CSS Backgrounds and Borders Module Level 3`_ is a candidate recommendation
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 also supports 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 Backgrounds and Borders Level 3: https://www.w3.org/TR/css-backgrounds-3/
.. _border part: https://www.w3.org/TR/css-backgrounds-3/#borders
.. _background part: https://www.w3.org/TR/css-backgrounds-3/#backgrounds
.. _rounded corners part: https://www.w3.org/TR/css-backgrounds-3/#corners
.. _border images part: https://www.w3.org/TR/css-backgrounds-3/#border-images
.. _box shadow part: https://www.w3.org/TR/css-backgrounds-3/#misc
.. _git branch: https://github.com/Kozea/WeasyPrint/pull/149

CSS Image Values and Replaced Content Module Level 3 / 4
++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The `Image Values and Replaced Content Module Level 3`_ is a candidate
recommendation 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 ``object-fit`` and ``object-position`` properties are supported.

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

The ``image-rendering`` and ``image-orientation`` properties are supported.

.. _Image Values and Replaced Content Module Level 3: https://www.w3.org/TR/css-images-3/
.. _Image Values and Replaced Content Module Level 4: https://www.w3.org/TR/css-images-4/

CSS Box Sizing Module Level 3
+++++++++++++++++++++++++++++

The `CSS Box Sizing Module Level 3`_ is a candidate recommendation extending
"the CSS sizing properties with keywords that represent content-based
'intrinsic' sizes and context-based 'extrinsic' sizes."

The new property defined in this document is implemented in WeasyPrint:
``box-sizing``.

The ``min-content``, ``max-content`` and ``fit-content()`` sizing values are
**not** supported.

.. _CSS Box Sizing Module Level 3: https://www.w3.org/TR/css-sizing-3/

CSS Overflow Module Level 3
+++++++++++++++++++++++++++

The `CSS Overflow Module Level 3`_ is a working draft containing "the features
of CSS relating to scrollable overflow handling in visual media."

The ``overflow`` property is supported, as defined in CSS2. ``overflow-x``,
``overflow-y``, ``overflow-clip-margin``, ``overflow-inline`` and
``overflow-block`` are **not** supported.

The ``text-overflow``, ``block-ellipsis``, ``line-clamp``, ``max-lines`` and
``continue`` properties are supported.

.. _CSS Overflow Module Level 3: https://www.w3.org/TR/2020/WD-css-overflow-3-20200603/

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.

The ``calc()`` function is **not** supported.

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

.. _CSS Values and Units Module Level 3: https://www.w3.org/TR/css3-values/

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
supported.

The ``column-span`` property is supported for direct children of columns.

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

.. _CSS Multi-column Layout Module: https://www.w3.org/TR/css-multicol-1/

CSS Fragmentation Module Level 3 / 4
++++++++++++++++++++++++++++++++++++

The `CSS Fragmentation Module Level 3`_ "describes the fragmentation model that
partitions a flow into pages, columns, or regions. It builds on the Page model
module and introduces and defines the fragmentation model. It adds
functionality for pagination, breaking variable fragment size and orientation,
widows and orphans."

The `CSS Fragmentation Module Level 4`_ is a working draft on the same subject.

The ``break-before``, ``break-after`` and ``break-inside`` properties are
supported for pages, but **not** for columns and regions. ``page-break-*``
aliases as defined in CSS2 are supported too.

The ``orphans`` and ``widows`` properties are supported.

The ``box-decoration-break`` property is supported, but backgrounds are always
repeated and not extended through the whole box as it should be with 'slice'
value.

The ``margin-break`` property is supported.

.. _CSS Fragmentation Module Level 3: https://www.w3.org/TR/css-break-3/
.. _CSS Fragmentation Module Level 4: https://www.w3.org/TR/css-break-4/

CSS Custom Properties for Cascading Variables Module Level 1
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The `CSS Custom Properties for Cascading Variables Module Level 1`_ "introduces
cascading variables as a new primitive value type that is accepted by all CSS
properties, and custom properties for defining them."

The custom properties and the ``var()`` notation are supported.

.. _CSS Custom Properties for Cascading Variables Module Level 1: https://www.w3.org/TR/css-variables/

CSS Text Decoration Module Level 3 / 4
++++++++++++++++++++++++++++++++++++++

The `CSS Text Decoration Module Level 3`_ "contains the features of CSS
relating to text decoration, such as underlines, text shadows, and emphasis
marks."

The `CSS Text Decoration Module Level 4`_ is a working draft on the same subject.

The ``text-decoration-line``, ``text-decoration-style``,
``text-decoration-color``, ``text-decoration-thickness`` and
``text-underline-offset`` properties are supported. The ``text-decoration``
shorthand is also supported.

The other properties (``text-underline-position``, ``text-emphasis-*``,
``text-shadow``) are not supported.

.. _CSS Text Decoration Module Level 3: https://www.w3.org/TR/css-text-decor-3/
.. _CSS Text Decoration Module Level 4: https://www.w3.org/TR/css-text-decor-4/

CSS Flexible Box Layout Module Level 1
++++++++++++++++++++++++++++++++++++++

The `CSS Flexible Box Layout Module Level 1`_ "describes a CSS box model
optimized for user interface design", also known as "flexbox".

This module works for simple use cases but is not deeply tested.

All the ``flex-*``, ``align-*``, ``justify-*`` and ``order`` properties are
supported. The ``flex`` and ``flex-flow`` shorthands are supported too.

.. _CSS Flexible Box Layout Module Level 1: https://www.w3.org/TR/css-flexbox-1/

CSS Grid Layout Module Level 2
++++++++++++++++++++++++++++++

The `CSS Grid Layout Module Level 2`_ "defines a two-dimensional grid-based layout
system, optimized for user interface design".

This module works for simple cases, but has some limitations. Here are
non-exhaustive lists of supported/unsupported features.

Supported:

- ``display: grid``,
- ``grid-auto-*``, ``grid-template-*`` and other ``grid-*`` properties,
- ``grid`` and other ``grid-*`` shorthands,
- flexible lengths (``fr`` unit),
- line names,
- grid areas,
- auto rows and auto columns,
- ``z-index``,
- ``repeat(X, *)``,
- ``minmax()``,
- ``align-*`` and ``justify-*`` alignment properties,
- ``gap`` and ``*-gap`` properties for gutters,
- dense auto flow,
- ``order``,
- margins, borders, padding on grid containers and grid items,
- fragmentation between rows.

Unsupported or untested:

- ``display: inline-grid``,
- auto content size for grid containers,
- ``grid-auto-flow: column``,
- subgrids,
- ``repeat(auto-fill, *)`` and ``repeat(auto-fit, *)``,
- auto margins for grid items,
- ``span`` with line names,
- ``span`` for flexible tracks,
- ``safe`` and ``unsafe`` alignments,
- baseline alignment,
- grid items with intrinsic size (images),
- distribute space beyond limits,
- grid items larger than grid containers,
- ``min-width``, ``max-width``, ``min-height``, ``max-height`` on grid items,
- complex ``min-content`` and ``max-content`` cases,
- absolutely positioned and floating grid items,
- fragmentation in rows.

.. _CSS Grid Layout Module Level 2: https://www.w3.org/TR/css-grid-2/

CSS Basic User Interface Module Level 3/4
+++++++++++++++++++++++++++++++++++++++++

The `CSS Basic User Interface Module Level 3/4`_ "enables authors to style user
interface related properties and values."

The ``outline-width``, ``outline-style``, ``outline-color`` properties and the
``outline`` shorthand are supported. The ``outline-offset`` property is also
supported.

The ``resize``, ``cursor``, ``caret-*`` and ``nav-*`` properties are **not**
supported.

The ``appearance`` property is supported. When set to ``auto``, it displays
form fields as PDF form fields (supported for text inputs, check boxes, text
areas, and select only).

The ``accent-color`` property is **not** supported.
