Documentation
¶
Overview ¶
Package paginate cuts a laid-out document into pages: it returns the document y at which each page after the first starts, honouring CSS Fragmentation Level 3 as far as a page medium needs it — forced breaks (break-before/after: page, left, right and the page-break-* aliases), break-inside: avoid, break-before/after: avoid (keep with the previous or the next content), orphans and widows — over the atoms a page can cut between.
Atoms ¶
A page can only be cut between atoms: a text line, a whole table row (never split mid-row — unless the row is a layout-table wrapper whose cell holds a nested table, in which case its real rows are the atoms), or a leaf box with height and no lines (a rule, a spacer). This is the rule the PDF exporter go-pdfkit/html2pdf paginated with before the CSS properties were read at all, and it is what keeps a line from being sliced across two pages.
Constraints, and the order they yield in ¶
A forced break is always taken, even on a page that is nearly empty. Between forced breaks a page is filled as far as it goes, and the cut is the last boundary that respects, in the spec's order of precedence: the break-before/after: avoid of the atoms on either side and every break-inside: avoid box that could fit on a page (rules 1, 2 and 4), then orphans and widows (rule 3). When no boundary respects everything, the orphans/widows rule is dropped first, then the avoid rules, exactly as css-break-3 §5.4 prescribes; a box taller than a page is never kept together, since it cannot be. An atom taller than a page overflows its own page's bottom rather than blocking pagination.
Margins adjoining an unforced break are not truncated (css-break-3 §5.5): the atoms' positions are the layout's, and a block's top margin before a cut reappears as a blank at the next page's top. A consumer that paints pages by shifting the document accepts that today.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Options ¶
type Options struct {
// PageHeight is the usable height of a page, in the layout's CSS px —
// the page area, margins already taken out.
PageHeight float64
// FirstPageHeight, when non-zero, is the first page's usable height (an
// @page :first with different margins); every later page uses PageHeight.
FirstPageHeight float64
}
Options tunes Paginate.
Source Files