mirror of
https://github.com/Kozea/WeasyPrint.git
synced 2024-10-05 00:21:15 +03:00
717 lines
27 KiB
ReStructuredText
717 lines
27 KiB
ReStructuredText
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
|
||
|
||
.. module:: weasyprint.document
|
||
.. autoclass:: Document
|
||
:members:
|
||
.. autoclass:: DocumentMetadata()
|
||
:members:
|
||
.. autoclass:: Page()
|
||
:members:
|
||
|
||
.. 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: http://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/master/weasyprint/css/html5_ua.css
|
||
.. _presentational hints: http://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/master/weasyprint/css/html5_ua.css
|
||
.. _cascade: http://www.w3.org/TR/CSS21/cascade.html#cascading-order
|
||
.. _!important: http://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 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 `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.
|
||
|
||
|
||
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`` or ``~/.fonts`` directory is generally enough
|
||
to install a new font. WeasyPrint should support `any font format handled by
|
||
FreeType`_.
|
||
|
||
.. _any font format handled by FreeType: https://en.wikipedia.org/wiki/FreeType#File_formats
|
||
|
||
|
||
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: http://www.w3.org/TR/CSS21/
|
||
.. _Acid2 Test: http://www.webstandards.org/files/acid2/test.html
|
||
.. _::first-line: http://www.w3.org/TR/CSS21/selector.html#first-line-pseudo
|
||
.. _empty-cells: http://www.w3.org/TR/CSS21/tables.html#empty-cells
|
||
.. _visibility\: collapse: http://www.w3.org/TR/CSS21/tables.html#dynamic-effects
|
||
.. _width: http://www.w3.org/TR/CSS21/visudet.html#min-max-widths
|
||
.. _height: http://www.w3.org/TR/CSS21/visudet.html#min-max-heights
|
||
.. _font matching algorithm: http://www.w3.org/TR/CSS21/fonts.html#algorithm
|
||
.. _Bi-directional text: http://www.w3.org/TR/CSS21/visuren.html#direction
|
||
.. _System colors: http://www.w3.org/TR/CSS21/ui.html#system-colors
|
||
.. _system fonts: http://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
|
||
+++++++++++++++++
|
||
|
||
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.
|
||
|
||
.. _Selectors Level 3: http://www.w3.org/TR/css3-selectors/
|
||
|
||
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-size`` 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`_.
|
||
|
||
.. 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`` 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 ``text-align`` property with an alignment character;
|
||
- the ``pre-wrap-auto`` value of the ``white-space`` property; and
|
||
- the ``text-spacing`` property.
|
||
|
||
.. _supported by Pyphen: https://github.com/Kozea/Pyphen/tree/master/pyphen/dictionaries
|
||
.. _hyphenation: http://www.w3.org/TR/css3-text/#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
|
||
++++++++++++++++++++++++
|
||
|
||
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, provided that Pango >= 1.38 is installed.
|
||
|
||
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 limitations `#93`_);
|
||
- the page ``size``, ``bleed`` and ``marks`` properties;
|
||
- the named pages.
|
||
|
||
.. _CSS Paged Media Module Level 3: http://dev.w3.org/csswg/css3-page/
|
||
.. _#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 */
|
||
|
||
You can also use `running elements`_ to put HTML boxes into the page margins
|
||
(but the ``start`` parameter of ``element()`` is not supported).
|
||
|
||
The other features of GCPM are **not** implemented:
|
||
|
||
- footnotes (``float: footnote``, ``footnote-display``, ``footnote`` counter,
|
||
``::footnote-call``, ``::footnote-marker``, ``@footnote`` rule,
|
||
``footnote-policy``);
|
||
- page groups (``:nth(X of pagename)`` pseudo-class).
|
||
|
||
.. _CSS Generated Content for Paged Media Module: http://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
|
||
|
||
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 experimental_
|
||
``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 }
|
||
|
||
The other features of this module are **not** implemented:
|
||
|
||
- quotes (``content: *-quote``);
|
||
- leaders (``content: leader()``).
|
||
|
||
.. _CSS Generated Content Module Level 3: http://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
|
||
.. _experimental: http://www.w3.org/TR/css-2010/#experimental
|
||
.. _user agent stylesheet: https://github.com/Kozea/WeasyPrint/blob/master/weasyprint/css/html5_ua.css
|
||
|
||
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: http://www.w3.org/TR/css3-color/
|
||
|
||
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 Transforms Module Level 1: http://dev.w3.org/csswg/css3-transforms/
|
||
|
||
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 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 Backgrounds and Borders Level 3: http://www.w3.org/TR/css3-background/
|
||
.. _border part: http://www.w3.org/TR/css3-background/#borders
|
||
.. _background part: http://www.w3.org/TR/css3-background/#backgrounds
|
||
.. _rounded corners part: http://www.w3.org/TR/css3-background/#corners
|
||
.. _border images part: http://www.w3.org/TR/css3-background/#border-images
|
||
.. _box shadow part: http://www.w3.org/TR/css3-background/#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`` property is supported.
|
||
|
||
The ``image-orientation`` property is **not** supported.
|
||
|
||
.. _Image Values and Replaced Content Module Level 3: http://www.w3.org/TR/css3-images/
|
||
.. _Image Values and Replaced Content Module Level 4: http://www.w3.org/TR/css4-images/
|
||
|
||
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.
|
||
|
||
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
|
||
**not** 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/css3-multicol/
|
||
|
||
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
|
||
++++++++++++++++++++++++++++++++++
|
||
|
||
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 ``text-decoration-line``, ``text-decoration-style`` and
|
||
``text-decoration-color`` properties are supported, except from the ``wavy``
|
||
value of ``text-decoration-style``. 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 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/
|