resolves #1730 allow theme to position caption for code and example blocks below block using caption-end key (PR #2180)

4 files changed, 40 insertions, 4 deletions

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index d1847c9e..3bac879e 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -9,6 +9,7 @@ For a detailed view of what has changed, refer to the {url-repo}/commits/main[co
 
 Enhancements::
 
+* allow theme to position caption for code and example blocks below block using `caption-end` key (#1730)
 * allow hyphenation to be turned on and configured using the `base-hyphens` key in the theme (#2161)
 * replace `docdir` attribute reference in value of `pdf-themesdir` and `pdf-fontsdir` attributes (if not already replaced) (#412)
 * split out `start_title_page` method from `ink_title_page` to make customization of the title page simpler using an extended converter
diff --git a/lib/asciidoctor/pdf/converter.rb b/lib/asciidoctor/pdf/converter.rb
index 95ea4bd2..a95d5f38 100644
--- a/lib/asciidoctor/pdf/converter.rb
+++ b/lib/asciidoctor/pdf/converter.rb
@@ -1133,10 +1133,11 @@ module Asciidoctor
           adjusted_font_size = ((node.option? 'autofit') || (node.document.attr? 'autofit-option')) ? (compute_autofit_font_size source_chunks, :code) : nil
         end
 
+        caption_below = @theme.code_caption_end&.to_sym == :bottom
         arrange_block node do |extent|
           add_dest_for_block node if node.id
           tare_first_page_content_stream do
-            theme_fill_and_stroke_block :code, extent, background_color: bg_color_override, caption_node: node
+            theme_fill_and_stroke_block :code, extent, background_color: bg_color_override, caption_node: caption_below ? nil : node
           end
           pad_box @theme.code_padding, node do
             theme_font :code do
@@ -1148,7 +1149,8 @@ module Asciidoctor
             end
           end
         end
-
+        # TODO: add protection against the bottom caption being widowed
+        ink_caption node, category: :code, end: :bottom if caption_below
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
@@ -1158,10 +1160,11 @@ module Asciidoctor
 
       def convert_example node
         return convert_open node if node.option? 'collapsible'
+        caption_bottom = @theme.example_caption_end&.to_sym == :bottom
         arrange_block node do |extent|
           add_dest_for_block node if node.id
           tare_first_page_content_stream do
-            theme_fill_and_stroke_block :example, extent, caption_node: node
+            theme_fill_and_stroke_block :example, extent, caption_node: caption_bottom ? nil : node
           end
           pad_box @theme.example_padding, node do
             theme_font :example do
@@ -1169,6 +1172,8 @@ module Asciidoctor
             end
           end
         end
+        # TODO: add protection against the bottom caption being widowed
+        ink_caption node, category: :example, end: :bottom if caption_bottom
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
diff --git a/spec/example_spec.rb b/spec/example_spec.rb
index 0e077d54..4060f655 100644
--- a/spec/example_spec.rb
+++ b/spec/example_spec.rb
@@ -182,6 +182,21 @@ describe 'Asciidoctor::PDF::Converter - Example' do
     (expect title_text[:font_name]).to eql 'NotoSerif-Bold'
   end
 
+  it 'should allow theme to place caption below block' do
+    pdf_theme = { example_caption_end: 'bottom' }
+
+    pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true
+    .Look out below!
+    ====
+    content
+    ====
+    EOS
+
+    content_text = pdf.find_unique_text 'content'
+    title_text = pdf.find_unique_text 'Example 1. Look out below!'
+    (expect title_text[:y]).to be < content_text[:y]
+  end
+
   it 'should apply text decoration to caption' do
     pdf_theme = {
       caption_text_decoration: 'underline',
diff --git a/spec/listing_spec.rb b/spec/listing_spec.rb
index 87aede56..0b01087f 100644
--- a/spec/listing_spec.rb
+++ b/spec/listing_spec.rb
@@ -467,12 +467,27 @@ describe 'Asciidoctor::PDF::Converter - Listing' do
     ----
     EOS
 
-    title_text = (pdf.find_text 'Caption with background color')[0]
+    title_text = pdf.find_unique_text 'Caption with background color'
     (expect title_text[:font_color]).to eql 'FFFFFF'
     (expect title_text[:font_name]).to eql 'NotoSerif-Bold'
     (expect pdf.pages[0][:raw_content]).to include %(/DeviceRGB cs\n0.66667 0.0 0.0 scn\n48.24 790.899 498.8 14.991 re)
   end
 
+  it 'should allow theme to place caption below block' do
+    pdf_theme = { code_caption_end: 'bottom' }
+
+    pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true
+    .Look out below!
+    ----
+    code
+    ----
+    EOS
+
+    content_text = pdf.find_unique_text 'code'
+    title_text = pdf.find_unique_text 'Look out below!'
+    (expect title_text[:y]).to be < content_text[:y]
+  end
+
   it 'should apply inline formatting if quotes subs is enabled' do
     pdf = to_pdf <<~'EOS', analyze: true
     [subs=+quotes]