Splitting

When an item doesn't fit on the current page, Format can split it and continue it on the next. Set splitGranularity on its Flow to choose where breaks are allowed.

Split granularity

The default is none, which keeps each item together. Choose a finer granularity to allow breaks within an item.

A grapheme cluster is a character as a reader sees it, such as a letter with an accent or an emoji. Choose a granularity that keeps your content readable across page breaks.

What survives a split

When an item breaks across pages, Format preserves its surrounding HTML on each page. Scaffolding also repeats:

• Flow scaffolding, such as table headers and list wrappers, appears on every page containing that Flow's content. This also applies to nested Flows.
• Layout scaffolding, such as page headers and footers, appears on every page the Layout creates.

Only the content at the Stream position splits. See Scaffolding for examples of repeating markup.

Style a split item

Use the data-split attributes to style content that spans pages. Format adds them to each part, or fragment, of a split element. The attributes have no value; select them by name.

An element that stays on one page has none of these attributes, even if Format moves it to the next page. Nested elements are marked separately: a list can span several pages while an individual list item stays on one page.

Use these selectors in your Layout's CSS:

For example, remove the first-line indent from a continued paragraph and the borders where a callout splits:

/* Remove the indent when a paragraph continues on another page. */
p[data-split-continued] {
  text-indent: 0;
}

/* Remove the bottom border when more content follows. */
.callout[data-split]:not([data-split-end]) {
  border-bottom: 0;
}

/* Remove the top border on every continuation. */
.callout[data-split-continued] {
  border-top: 0;
}

Format accounts for these styles when laying out each page, including any space added by ::before or ::after. For a continuation heading or notice on a Flow, see Style a Flow's continuation.

By default, a list item's bullet or number appears only on the page where the item begins. If you set content in a custom ::marker rule, add :not([data-split-continued]) to its selector to avoid repeating the marker.

Per-Flow granularity

Each Flow has its own splitGranularity, which applies to the items in its stream. Nested Flows do not inherit this setting. A Flow that omits it uses none, regardless of the surrounding Flow or Layout.

When no useful split is possible

When an item doesn't fit, Format uses the selected granularity to place as much as possible on the current page. If no part fits, or splitting is set to none, it moves the whole item to the next page.

The empty-page exception

If an item cannot fit or split on an otherwise empty page, Format places it there anyway. The Flow's next item starts on the following page.

An oversized item may extend beyond the page. Set overflow: hidden on its surrounding element to clip it. To avoid overflow, allow finer splitting or use a nested Flow to divide the content into smaller items.

Picking the right granularity

• Use none for items that should stay together, such as invoice rows, profile cards, or an image with its caption.
• Use sentence when a sentence should stay on one page, such as a short legal clause.
• Use word for letters, articles, books, and reports.
• Use grapheme for long, unbroken strings, such as URLs or identifiers. It can break within a word.

Related

• Pagination
• Scaffolding
• SplitGranularity
• Flow
• Stream