Inconsistencies with the priority of @page rules and the documentation
Short version:
Order priority of @page
rules should be the following for any rule:
- @page { }
- @page :left { } or @page :right { }
- @page :blank { }
- @page :first { }
- @page :nth() { }
- @page namedPage { }
- @page namedPage :left { } or @page namedPage :right { }
- @page namedPage :blank { } (if supported in the future)
- @page namedPage :first { }
- @page namedPage :nth() { } (if supported in the future)
For now, :first
and :left
/:right
named pages don't work properly for classic rules (but work for generated content), and the named pages documentation is incorrect.
Long version:
The named pages documentation says the following:
In paged.js, the page rules do not apply quite in cascade. The rules are defined by the order of priority below (ranked from lowest to highest priority):
- @page { }
- @page :left { } or @page :right { }
- @page namedPage { }
- @page namedPage :left { } or @page namedPage :right { }
- @page :blank { }
- @page :first { }
If a CSS property is defined in a lower priority page than another but not in the priority page, then the priority page inherits this property and its value. Otherwise, the property will take the new value defined in the priority page.
While in the code, when it comes to running elements in margin boxes, the page weight is applied like this (I took the comment from the code and it seems accurate (src\modules\generated-content\running-headers.js
)):
/**
* Assign a weight to @page selector classes
* 1) page
* 2) left & right
* 3) blank
* 4) first & nth
* 5) named page
* 6) named left & right
* 7) named first & nth
* @param {string} [s] selector string
* @return {int} weight
*/
This behaviour is different, and I didn't find any mention to this in the docs. If the difference is intented (I guess it's not), it should be written in the chapter about generated content in margin boxes, or in the chapter about generated content.
But to be fair, I think the second priority order should be used for all rules, not only the display of running elements.
Moreover, the priority order described in the named pages documentation doesn't seem to be true. It seems to be:
- @page { }
- @page :left { } or @page :right { }
- @page :blank { }
- @page :first { } (I wasn't able to test :blank and :first at the same time)
- @page :nth() { }
- @page namedPage { }
- @page namedPage :first { } or ( @page namedPage :left { } or @page namedPage :right { } ), depending on which is the latest in the CSS
As you can see, the order from the doc is incorrect. Named pages have higher priority (as they should have, in my opinion).
There is also a problem when it comes to the priority of :first
and :left
/:right
named pages. It seems like they have the same one. The following code will result in a blue background (and the opposite in a magenta):
@page custom:first {
background: magenta;
}
@page custom:right {
background: blue;
}
:first
named pages should have a higher priority than :left
/:right
named pages, as it is the case for their generated content in margin boxes.
:blank
/:nth()
named pages are not supported yet, so I didn't test it.