An asciidoctor-pdf extension that forces page breaks inside tables, with repeating headers, seamless borders, and footer only on the last page.

A rendered demo is available at demo/demo.pdf.

Installation

gem install asciidoctor-pdf-table-break

Or add to a Gemfile:

gem 'asciidoctor-pdf-table-break'

Usage

Require the extension on the command line:

asciidoctor-pdf -r asciidoctor-pdf-table-break document.adoc

Syntax

Insert a break row at the point where you want the page break. Two equivalent forms are supported:

Form 1 — colspan span (recommended)

Use AsciiDoc’s N+| span syntax, where N is the number of columns:

[%header]
|===
| Name | Value

| Row 1 | alpha
| Row 2 | beta

2+| <<<

| Row 3 | gamma
|===

Form 2 — one cell per column

Write one | <<< per column:

[%header]
|===
| Name | Value

| Row 1 | alpha
| Row 2 | beta

| <<< | <<<

| Row 3 | gamma
|===

Keeping HTML/Antora output clean

Wrap break rows in ifdef::backend-pdf[] so they are invisible to the HTML5 and Antora converters:

[%header]
|===
| Name | Value

| Row 1 | alpha
| Row 2 | beta

ifdef::backend-pdf[]
2+| <<<
endif::[]

| Row 3 | gamma
|===

Behavior

  • Break rows are not rendered — they exist only as page-break markers.

  • Header rows repeat on every continuation page.

  • Footer rows appear only on the last page segment.

  • The table caption/title and anchor appear only on the first page.

  • Borders are seamless: the outer frame border is replaced by the grid line width at break boundaries, so the table looks identical to one that breaks naturally.

Multiple breaks

You can insert as many break rows as needed:

|===
| A | B | C

| 1 | 2 | 3

ifdef::backend-pdf[]
3+| <<<
endif::[]

| 4 | 5 | 6

ifdef::backend-pdf[]
3+| <<<
endif::[]

| 7 | 8 | 9
|===

Background

asciidoctor-pdf has no built-in mechanism to force a page break at a specific row within a table. The <<< page-break paragraph works between blocks but not inside a table. This extension monkey-patches Asciidoctor::PDF::Converter#convert_table via Module#prepend to detect break rows and render each segment as a separate table on its own page.

A native implementation of this feature has been proposed upstream at asciidoctor/asciidoctor-pdf. This gem is a stopgap for users who need the feature now.

Compatibility

Tested against asciidoctor-pdf 2.3.x and later. Uses Module#prepend so it is compatible with other extensions that subclass or prepend the converter.

License

MIT — see LICENSE.