document how to add breakable option to all tables at runtime using Asciidoctor extension

3 files changed, 32 insertions, 0 deletions

diff --git a/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc b/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc
index fb70d351..1e4c4f42 100644
--- a/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc
+++ b/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc
@@ -194,4 +194,7 @@ 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 xref:extend:use-cases.adoc#breakable-tables[breakable tables] to find the code for this extension.
 ****
diff --git a/docs/modules/extend/examples/breakable-tables-tree-processor.rb b/docs/modules/extend/examples/breakable-tables-tree-processor.rb
new file mode 100644
index 00000000..5311aab1
--- /dev/null
+++ b/docs/modules/extend/examples/breakable-tables-tree-processor.rb
@@ -0,0 +1,12 @@
+Asciidoctor::Extensions.register do
+  tree_processor do
+    process do |doc|
+      doc.find_by context: :table do |table|
+        unless (table.option? 'breakable') || (table.option? 'unbreakable')
+          table.set_option 'breakable'
+        end
+      end
+      doc
+    end
+  end
+end
diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc
index 083ef4c6..5fe9c12a 100644
--- a/docs/modules/extend/pages/use-cases.adoc
+++ b/docs/modules/extend/pages/use-cases.adoc
@@ -231,6 +231,23 @@ include::example$pdf-converter-additional-toc-entries.rb[]
 The depth of the TOC is automatically controlled by the `toclevels` attributes.
 Once this limit is reached, the converter will not call `get_entries_for_toc` for that parent (as none of its children will be included in the TOC).
 
+[#breakable-tables]
+== Breakable tables
+
+As explained on xref:ROOT:breakable-and-unbreakable.adoc[], tables are not configured with orphan prevention of the anchor and title by default.
+In order to activate this behavior, the `breakable` option must be specified on the table.
+
+To avoid having to add this option on every table, you can use an Asciidoctor extension to add it at runtime.
+This use case employs a tree processor rather than an extended PDF converter, though its behavior does impact conversion.
+
+.Extension that adds the breakable option to all tables
+[,ruby]
+----
+include::example$breakable-tables-tree-processor.rb[]
+----
+
+This same technique can be used to add the `breakable` or `unbreakable` option at runtime to any blocks of your choosing.
+
 == Narrow TOC
 
 Let's say you want to make the content on the TOC page(s) really narrow.