asciidoctor-pdf-table-break 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de514b2984c827ec505996e116fda87ad5134ae4e82e74ecf0e99286af856fa1
+  data.tar.gz: 9430c1c541b26c9b1e7bf7424d30d93e4f96ef6aba3a7b47b5ab6e82413e593a
+SHA512:
+  metadata.gz: 0ffbe8393f1a7faa61ef82ee4bb1879496f82ce8f624bfadba6beb4c0198290a54eb8ff0a8f5cb4ef6759f5e27098a6904f9461a4d964a2db80333f31adc312c
+  data.tar.gz: 5ed03de5ba3d9ab53ea1955b4b8e8845d32ea769e7aa9387f4da24b25e89bdce619faf6d4173b030ce61c5e512a81fb312fcc570809345235e0685ede5422ca1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 白一百 baiyibai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.adoc

@@ -0,0 +1,148 @@
+= asciidoctor-pdf-table-break
+:toc: left
+:toclevels: 2
+:source-highlighter: highlight.js
+
+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 link:demo/demo.pdf[].
+
+== Installation
+
+[source,bash]
+----
+gem install asciidoctor-pdf-table-break
+----
+
+Or add to a `Gemfile`:
+
+[source,ruby]
+----
+gem 'asciidoctor-pdf-table-break'
+----
+
+== Usage
+
+Require the extension on the command line:
+
+[source,bash]
+----
+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:
+
+[source,asciidoc]
+----
+[%header]
+|===
+| Name | Value
+
+| Row 1 | alpha
+| Row 2 | beta
+
+2+| <<<
+
+| Row 3 | gamma
+|===
+----
+
+=== Form 2 — one cell per column
+
+Write one `| <<<` per column:
+
+[source,asciidoc]
+----
+[%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:
+
+[source,asciidoc]
+----
+[%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:
+
+[source,asciidoc]
+----
+|===
+| 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
+https://github.com/asciidoctor/asciidoctor-pdf[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 link:LICENSE[].

data/demo/demo.adoc

@@ -0,0 +1,117 @@
+= asciidoctor-table-break demo
+:doctype: article
+:toc:
+:toclevels: 2
+:sectanchors:
+
+This document demonstrates the `asciidoctor-table-break` extension.
+Each break row (`2+| <<<`) forces a new page inside the table while keeping headers repeating and borders seamless.
+
+== Basic break with repeating header
+
+The table below has a header row and a break after row 2.
+The header repeats on the second page.
+
+[%header]
+|===
+| Name | Value
+
+| Row 1 | alpha
+| Row 2 | beta
+
+ifdef::backend-pdf[]
+2+| <<<
+endif::[]
+
+| Row 3 | gamma
+| Row 4 | delta
+| Row 5 | epsilon
+|===
+
+== Break with footer
+
+The footer row (`Total`) appears only on the last page segment.
+
+[%header%footer]
+|===
+| Item | Quantity | Unit Price
+
+| Apple      |  10 | $0.50
+| Banana     |   6 | $0.30
+| Cherry     | 100 | $0.10
+| Date       |  20 | $1.20
+| Elderberry |   5 | $3.00
+
+ifdef::backend-pdf[]
+3+| <<<
+endif::[]
+
+| Fig        |  15 | $0.80
+| Grape      |  40 | $0.25
+| Honeydew   |   2 | $4.50
+| Jackfruit  |   1 | $8.00
+| Kiwi       |  12 | $0.60
+
+| Total      | 211 |
+|===
+
+== Multiple breaks (three pages)
+
+A three-column reference table split across three pages.
+
+[%header]
+|===
+| Country | Capital | Population (M)
+
+| Argentina  | Buenos Aires  | 46.1
+| Australia  | Canberra      | 26.5
+| Brazil     | Brasília      | 215.3
+| Canada     | Ottawa        | 38.2
+| China      | Beijing       | 1412.0
+
+ifdef::backend-pdf[]
+3+| <<<
+endif::[]
+
+| Egypt      | Cairo         | 105.0
+| France     | Paris         | 68.0
+| Germany    | Berlin        | 83.8
+| India      | New Delhi     | 1428.0
+| Japan      | Tokyo         | 124.5
+
+ifdef::backend-pdf[]
+3+| <<<
+endif::[]
+
+| Mexico     | Mexico City   | 128.5
+| Nigeria    | Abuja         | 223.8
+| Russia     | Moscow        | 144.1
+| Spain      | Madrid        | 47.4
+| USA        | Washington DC | 335.9
+|===
+
+== Captioned table
+
+The title and anchor appear only on the first page segment.
+
+.Software release history
+[%header,#tbl-releases]
+|===
+| Version | Date       | Highlights
+
+| 3.0     | 2024-01-15 | Complete rewrite, new theme engine
+| 2.3     | 2023-06-01 | Prawn 2.5 support, improved footnotes
+| 2.2     | 2022-11-20 | Running header/footer theming
+| 2.1     | 2022-04-05 | SVG improvements, table captions
+| 2.0     | 2021-09-12 | Scratch converter, theming overhaul
+
+ifdef::backend-pdf[]
+3+| <<<
+endif::[]
+
+| 1.6     | 2020-07-18 | Index support
+| 1.5     | 2019-12-10 | Callout list improvements
+| 1.4     | 2019-03-27 | Multi-column layout
+| 1.3     | 2018-08-14 | TOC generation rewrite
+| 1.0     | 2017-01-31 | Initial stable release
+|===