Breakable and Unbreakable Blocks
Asciidoctor PDF gives the author some control over where content blocks are placed using the
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
If you want to prevent the orphaning of the anchor and title of a table, section, or discrete heading, then you add the
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.
The following blocks are breakable by default. This breakable behavior includes automatic anchor and title (i.e., caption) orphan prevention.
Code blocks (literal, listing, and source)
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.
Orphan prevention isn’t applied to tables, sections, and discrete headings by default.
This behavior can be enabled by adding the
Since these blocks are already breakable by default, this option is merely a publisher’s hint to inform the converter to add orphan prevention.
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 |===
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.,
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.
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.
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
heading: min-height-after: auto
Keep in mind that this does add extra processing to the conversion, which may impact conversion time.
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.
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. ====
unbreakable option can be assigned to individual blocks of the following types:
Code blocks (literal, listing, and source)
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] -- 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.