resolves #2075 keep section title with first block of content is breakable option is set on section (PR #2076)

3 files changed, 71 insertions, 13 deletions

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 790326d4..82976d20 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -10,6 +10,7 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/main[co
 Enhancements::
 
 * allow theme to control the border on all sides of tables independently (#902)
+* keep section title with first block of content is `breakable` option is set on section (#2075, #38)
 * pass `part`, `chapterlike`, and `hidden` options to `arrange_section` method
 
 == 2.0.0.alpha.1 (2022-04-20) - @mojavelinux
diff --git a/lib/asciidoctor/pdf/converter.rb b/lib/asciidoctor/pdf/converter.rb
index e3643b59..3c101a89 100644
--- a/lib/asciidoctor/pdf/converter.rb
+++ b/lib/asciidoctor/pdf/converter.rb
@@ -2870,16 +2870,37 @@ module Asciidoctor
 
       def arrange_section sect, title, opts
         return if opts[:hidden]
-        theme_font :heading, level: (hlevel = opts[:level]) do
-          # FIXME: this height doesn't account for impact of text transform or inline formatting
-          heading_height =
-            (height_of_typeset_text title) +
-            (@theme[%(heading_h#{hlevel}_margin_top)] || @theme.heading_margin_top) +
-            (@theme[%(heading_h#{hlevel}_margin_bottom)] || @theme.heading_margin_bottom)
-          heading_height += @theme.heading_min_height_after if sect.blocks? && @theme.heading_min_height_after
-          start_new_page unless cursor > heading_height
-          nil
+        if sect.option? 'breakable'
+          orphaned = nil
+          dry_run single_page: true do
+            start_page = page
+            theme_font :heading, level: opts[:level] do
+              if opts[:part]
+                layout_part_title sect, title, opts
+              elsif opts[:chapterlike]
+                layout_chapter_title sect, title, opts
+              else
+                layout_general_heading sect, title, opts
+              end
+            end
+            if page == start_page
+              page.tare_content_stream
+              orphaned = stop_if_first_page_empty { traverse sect }
+            end
+          end
+          start_new_page if orphaned
+        else
+          theme_font :heading, level: (hlevel = opts[:level]) do
+            # FIXME: this height doesn't account for impact of text transform or inline formatting
+            heading_height =
+              (height_of_typeset_text title) +
+              (@theme[%(heading_h#{hlevel}_margin_top)] || @theme.heading_margin_top) +
+              (@theme[%(heading_h#{hlevel}_margin_bottom)] || @theme.heading_margin_bottom)
+            heading_height += @theme.heading_min_height_after if sect.blocks? && @theme.heading_min_height_after
+            start_new_page unless cursor > heading_height
+          end
         end
+        nil
       end
 
       def layout_chapter_title node, title, opts = {}
diff --git a/spec/section_spec.rb b/spec/section_spec.rb
index 9dfe6dd1..4f36430d 100644
--- a/spec/section_spec.rb
+++ b/spec/section_spec.rb
@@ -872,15 +872,26 @@ describe 'Asciidoctor::PDF::Converter - Section' do
     create_class (Asciidoctor::Converter.for 'pdf') do
       register_for (backend = %(pdf#{object_id}).to_sym)
       def arrange_section sect, title, opts
+        return if opts[:hidden]
         orphaned = nil
         dry_run single_page: true do
           start_page = page
-          theme_font(:heading, level: opts[:level]) { layout_general_heading sect, title, opts }
-          next if page != start_page
-          page.tare_content_stream
-          orphaned = stop_if_first_page_empty { traverse sect }
+          theme_font :heading, level: opts[:level] do
+            if opts[:part]
+              layout_part_title sect, title, opts
+            elsif opts[:chapterlike]
+              layout_chapter_title sect, title, opts
+            else
+              layout_general_heading sect, title, opts
+            end
+          end
+          if page == start_page
+            page.tare_content_stream
+            orphaned = stop_if_first_page_empty { traverse sect }
+          end
         end
         start_new_page if orphaned
+        nil
       end
     end
 
@@ -907,6 +918,31 @@ describe 'Asciidoctor::PDF::Converter - Section' do
     (expect content_text[:page_number]).to be 2
   end
 
+  it 'should keep section with first block of content if breakable option is set on section' do
+    pdf = to_pdf <<~EOS, analyze: true
+    == Section A
+
+    image::tall.svg[pdfwidth=70mm]
+
+    [%breakable]
+    == Section B
+
+    [%unbreakable]
+    --
+    keep
+
+    this
+
+    together
+    --
+    EOS
+
+    section_b_text = pdf.find_unique_text 'Section B'
+    (expect section_b_text[:page_number]).to be 2
+    content_text = pdf.find_unique_text 'keep'
+    (expect content_text[:page_number]).to be 2
+  end
+
   it 'should not add break before chapter if heading-chapter-break-before key in theme is auto' do
     pdf = to_pdf <<~'EOS', pdf_theme: { heading_chapter_break_before: 'auto' }, analyze: true
     = Document Title