Pagination

Pagination is how Format breaks streamed content into a sequence of pages. Content flows through a Layout's Flows in document order; when a page fills, Format closes it and opens a new one with the same scaffolding repeated. The result is a paged document where page boundaries follow from the content, except where you author them explicitly with a PageBreak.

How a page is built

A rendered page is one instance of a Layout. Format renders the Layout's scaffolding (header, footer, anything outside a Flow) once per page. Then, inside the Layout's Flows, Format places each item from the Flow's stream one at a time, in document order.

How pages begin and end

Each Layout produces its own run of pages. Format opens a first page, renders the Layout's scaffolding, and places the stream's items into each Flow in document order.

Each Flow overflows against a region: the nearest ancestor Frame, or the page when no frame encloses it. A Frame is a height-constrained element inside the Layout that limits how much content fits before pagination. By default a Flow fills against the page itself, and it counts as full once its next item doesn't fit inside that region.

A Layout can hold more than one Flow: a main body and a sidebar, or a header line and a data table. Format fills each Flow from its own stream and the Flows advance independently.

A Flow stops filling on the current page in one of two ways. If its stream runs out of items, the Flow is finished for the document and won't render on any subsequent page. If the next item doesn't fit, Format tries to split it at the Flow's splitGranularity. If no useful split is possible, the whole item waits (with one edge case, covered in Splitting). Whether the split succeeds or not, the Flow is paused for the rest of the page.

The page closes once every Flow on it is either finished or paused. Format opens a new page, re-renders the Layout's scaffolding, and resumes the paused Flows from where they stopped. Finished Flows aren't rendered on the new page at all (see Scaffolding).

On any page, the Flows sit at different points in their streams. A long body row consumes more of its Flow than a short sidebar entry, so the body might be three items in while the sidebar is ten items in. The page closes around whatever each Flow placed so far.

This cycle continues, page by page, until every Flow in the Layout is empty.

Pagination strategies

A Flow's paginationStrategy field controls when Format breaks the page. A top-level Flow uses its own paginationStrategy; when that is unset, it falls back to the Layout's value, then to auto.

The auto strategy is the default. It fits content whose length you can't predict in advance: invoices, reports, statements, anything where the number of rows or pages changes from one render to the next.

The manual strategy is for documents where you want to control every page boundary yourself. Content that overflows the page runs past the visible area without breaking; the only way to start a new page is to author a PageBreak where you want one. This suits fixed, hand-designed documents (a four-page brochure, a one-page certificate) where the page count is part of the design.

A nested Flow follows its parent Flow's strategy. Format ignores a nested Flow's own paginationStrategy and applies the parent Flow's authored value instead; when the parent leaves it unset, the nested Flow falls back to the Layout's value, then to auto. Set paginationStrategy on a top-level Flow to control a whole branch of nested Flows at once.

PageBreak markers

A PageBreak sits in a Flow's stream. At a PageBreak, Format pauses the Flow: the next item is placed on a fresh page, even if there was still room on the current one. Other Flows on the page keep filling normally. The page closes once every Flow is either paused or finished, the same rule overflow follows.

PageBreaks are honored under both strategies, including manual, which otherwise ignores overflow.

Use a PageBreak wherever the page boundary matters more than how content fits: a chapter start, a year boundary, or a full-page chart that needs its own page.

Layout boundaries

Each Layout starts on a fresh page. When one Layout is finished, Format opens a new page for the next, even if there was room left on the previous page. This makes Layout boundaries a natural reset point: across Layouts, the page dimensions and even the orientation can change.

Within a single Layout, every page uses the same dimensions.

The page-number counter does not reset at Layout boundaries. It counts every rendered page in document order. To restart numbering, render Layouts as separate documents and stitch the PDFs together.

The item-processing loop

Here's the same idea expressed as a loop. Format runs this loop independently for each Flow, processing the stream item by item in document order:

1. Place the next item into the Flow, at its stream position.
2. Measure whether it fits inside the Flow's region.
3. If it fits, move to the next item.
4. If it doesn't fit, what happens depends on the Flow's pagination strategy:
   • auto (default): Format tries to split the item at the Flow's splitGranularity and places whatever fits, deferring the rest to the next page. If no useful split is possible, the whole item is deferred. See Splitting.
   • manual: Format ignores the overflow. The item stays on the current page (where it may visually spill past the edge) and Format continues with the next item.

Deferring has one exception. If deferring an unsplittable item would produce an empty page, Format places it anyway. This happens when the item is the first one Format tried to place in its Flow on this page and no other Flow has content to place: deferring would put the same problem on the next page. Format places the item as-is, so an oversized one extends past the page edge; your CSS controls whether that overflow is clipped or visible. The Flow then pauses.

When a Flow's next item doesn't fit, the Flow is paused for the rest of the page. Once every Flow is either paused or finished, Format closes the page and opens a new one (see How pages begin and end above). The loop continues until every Flow in the Layout is empty.

Nested Flows paginate inside their region

=======

A Flow placed inside another Flow's stream is an item like any other, with one addition: it paginates against its own region. It overflows against the nearest ancestor Frame, or the page when none encloses it, and repeats its own scaffolding on each page its content reaches. The nested Flow runs under its parent Flow's pagination strategy, not its own (see Pagination strategies above).

Overflow is handled the same way as for any other item. Format tries to split the nested Flow at its splitGranularity; whatever fits goes on the current page, the rest waits for the next. The nested Flow's own scaffolding (an outer <section>, a heading, a <tr> around table cells) survives on both pages; only the stream's items break. See Splitting.

Frames

A Flow's default region is the page: Format fills the Flow until the page is full, which is right for most documents. You can also place a Flow inside an explicit Frame to bound it to a region inside the Layout instead.

Use an explicit Frame when one of these applies:

• A Flow should fill a sub-region of the page, not the whole page. A notes aside caps the Flow at a fixed height, and a half-page chart area breaks the Flow once it overflows that half.
• Two Flows on the same page need different fill boundaries. Wrap each Flow in its own Frame so a two-column body and a sidebar break at their own heights.
• Other parts of the Layout need to react to the Flow's measured size. Format publishes Frame dimensions as CSS variables (--frame-<id>-height and --frame-<id>-sealed-height) so siblings can size themselves against them.

Format only paginates against a Frame when the Frame's height is bounded. Give it a height or max-height in CSS, or a definite size from a flex or grid parent. Without a bounded height, the Frame grows to fit whatever's inside it, and the Flow it contains never overflows.

Related

Splitting · Scaffolding · Frame · Flow · Stream · PageBreak · Layout