Breakable and Unbreakable Blocks

Asciidoctor PDF gives the author some control over where content blocks are placed using the unbreakable and breakable options, and tries to provide sensible defaults when these options are not used.

If you want a non-section block to be truly unbreakable, you add the unbreakable option. If you want to prevent the orphaning of the anchor and title of a table, section, or discrete heading, then you add the breakable option. Otherwise, you don’t need to specify either of these options as the default behavior should suffice. This page goes into detail about what functionality these options enable.

Breakable by default

The following blocks are breakable by default. This breakable behavior includes automatic anchor and title (i.e., caption) orphan prevention.

Admonitions
Block images
Code blocks (literal, listing, and source)
Examples
Open blocks
Quote blocks
Sidebars
Verses

Breakable with built-in anchor and title orphan prevention means that a block can break across pages, but the converter will automatically push the block to the next page, when necessary, to ensure a block’s anchor and title are kept with the block.

Tables, sections, and discrete headings are breakable by default, but do not provide automatic anchor and title orphan prevention. For tables, that means the anchor and title could be left on the current page if the table gets pushed to the next page. For sections, that means the section title may be left on the current page if the first block doesn’t fit below it. For discrete headings, that means the heading may be left on the current page if the next adjacent block doesn’t fit below it. However, you can turn on orphan prevention for tables, sections, and discrete headings by adding the (seemingly redundant) breakable option as a hint.

Breakable option

Orphan prevention isn’t applied to tables, sections, and discrete headings by default. This behavior can be enabled by adding the breakable option. Since these blocks are already breakable by default, this option is merely a publisher’s hint to inform the converter to add orphan prevention.

Table

The breakable option can be applied to a table to ensure the anchor and title (i.e., caption) are kept with the table if the table gets advanced to the next page.

.Optional table title
[#optional-id%breakable] (1)
|===
|Content |Content

|Content |Content
|===

1	Assign the `breakable` option to a table, using the shorthand percent symbol (`%`) for the `option` attribute name, to indicate that the table’s title and anchor should be kept with the table.

The behavior to keep the title with the table is only supported if the table caption is in its default end placement above the table (i.e., top). If the theme configures the caption end placement (table-caption-end) below the table (i.e., bottom), the title could be widowed on the next page. The lack of widow prevention for the title when placed below the table is due to a limitation in how this converter is implemented.

Section or discrete heading

The breakable option can be applied to a section to ensure the section title is kept with the first child block if that block gets advanced to the following page.

[%breakable]
=== Title of Section

First block of content in the section.

This option can also be added to a discrete heading to ensure the heading is kept with the next adjacent block if that block gets advanced to the next page.

[discrete%breakable]
=== Discrete Heading

Next block of content.

What the breakable option on a section or discrete heading does is prevent the converter from orphaning the title and its anchor. In other words, the option prevents a page break immediately following the title, so the title won’t be the last text on the page. Instead, the page break will come before the title. This option does not make the converter attempt to keep an entire section on the same page.

However, you can get the section title to stick with more than one block by wrapping the blocks that follow it in an unbreakable block.

[%breakable]
=== Title of Section

[%unbreakable]
--
First block of content in the section.

Second block of content in the section.
--

In this case, the section will follow the unbreakable block if it gets advanced to the next page.

If you want to prevent all sections and discrete headings from being orphaned globally, you can set the heading-min-height-after theme key to auto instead.

heading:
  min-height-after: auto

Keep in mind that this does add extra processing to the conversion, which may impact conversion time.

Other blocks

You don’t need to assign the breakable option any other block types because breakable is enabled by default and those other blocks already provide automatic orphan prevention.

Why do I need to specify breakable if it’s the default?

One of the challenges of AsciiDoc is that it’s a mature language, and that means we have to be careful when introducing functionality not to break existing documents and toolchains. Repurposing the use of the breakable option is one way to ensure that.

Given that all blocks are breakable by default, there’s no point in ever specifying the breakable option on the block for the purpose of making it breakable. And since it’s redundant, that provided an opportunity to use it as an author hint to mean something more without having to change the language.

When you add the breakable option to a block explicitly, the converter knows you placed it there. That provides an opportunity to enable functionality that isn’t enabled by default. That extra behavior, in this case, is to keep the anchor and title with the first row of a table, the first block of a section, and the next adjacent block of a discrete heading.

The reason the breakable option has to be specified explicitly on tables, sections, and discrete headings is because this computation comes at a slight cost in terms of performance and side effects. It’s minor, but it’s there. No other blocks require this.

Unbreakable option

When the unbreakable option is applied to a block, the converter will advance the block and its title and anchor to the next page if it detects that the block is going to break across pages and it can fit on a single page.

.Optional title of block
[%unbreakable] (1)
====
Content in an example block.

More content in an example block.
====

1	Assign the `unbreakable` option to a block, using the shorthand percent symbol (`%`) for the `option` attribute name, to prevent the block from breaking across pages.

The unbreakable option can be assigned to individual blocks of the following types:

Admonitions
Block images
Code blocks (literal, listing, and source)
Examples
Open blocks
Quote blocks
Sidebars
Tables
Verses

If a block with the unbreakable option is taller than a single page, it will not be advanced and, instead, break across pages. In this case, the automatic orphan protection is still applied.

The converter does not honor the unbreakable option on all content blocks in AsciiDoc, such as lists and paragraphs. In these cases, the author can elect to wrap the content in an open block with the unbreakable option.

[%unbreakable]
--
If this paragraph does not fit in the remaining space on this page,
and it is short enough to fit on a page by itself,
the converter will advance it to the next page so it does not break.
--

Internally, the open block enclosure is exactly how unbreakable is supported on tables.

Why can’t I assign unbreakable globally? Why don’t tables, sections, and discrete headings have orphan prevention by default?

The logic in the converter that calculates the extent of a block, which includes its title, main content, and padding, uses multiple passes, called “dry runs”, to get an accurate measurement of where a block begins, ends, and whether it breaks across pages. When the converter determines that a block’s title and anchor would be orphaned, or that a block breaks when it’s marked as unbreakable, it has to advance to the next page and convert it again in order to redo the extent calculation. This logic is vital for decorating the block with a border and background because the extent must be pixel accurate. All these dry runs add additional processing time and effort to the conversion.

Making all blocks unbreakable by default adds a lot of extra steps (not to mention leaving behind a lot of gaps in the document). Orphan prevents adds almost as many since it’s a similar process. Doing that by default for tables, sections, and discrete headings would be too complex and costly. To recoup some of the processing time, we decided to make some trade-offs. Therefore, blocks are breakable by default and authors must opt-in to get orphan prevention for tables, sections, and discrete headings.

However, you can add the breakable (or unbreakable option) to any block at runtime using an Asciidoctor extension. Refer to breakable tables to find the code for this extension.