asciidoctor-pdf 2.0.0.alpha.1 → 2.0.0.beta.1

data/lib/asciidoctor/pdf/converter.rb

@@ -139,6 +139,7 @@ module Asciidoctor
           # NOTE: enabling data-uri forces Asciidoctor Diagram to produce absolute image paths
           doc.attributes['data-uri'] = (doc.instance_variable_get :@attribute_overrides)['data-uri'] = ''
         end
+        @label = :primary
         @initial_instance_variables = [:@initial_instance_variables] + instance_variables
       end
 
@@ -164,8 +165,11 @@ module Asciidoctor
         if node.blocks?
           node.content
         elsif node.content_model != :compound && (string = node.content)
-          # TODO: this content could be cached on repeat invocations!
-          layout_prose string, (opts.merge hyphenate: true, margin_bottom: 0)
+          prose_opts = opts.merge hyphenate: true, margin_bottom: 0
+          if (bottom_gutter = @bottom_gutters[-1][node])
+            prose_opts[:bottom_gutter] = bottom_gutter
+          end
+          ink_prose string, prose_opts
         end
       ensure
         node.document.instance_variable_set :@converter, prev_converter if prev_converter
@@ -178,8 +182,9 @@ module Asciidoctor
       def convert_document doc
         doc.promote_preface_block
         init_pdf doc
-        # set default value for outline, pagenums, and show-link-uri if not otherwise set
+        # set default value for outline, outline-title, and pagenums attributes if not otherwise set
         doc.attributes['outline'] = '' unless (doc.attribute_locked? 'outline') || ((doc.instance_variable_get :@attributes_modified).include? 'outline')
+        doc.attributes['outline-title'] = '' unless (doc.attribute_locked? 'outline-title') || ((doc.instance_variable_get :@attributes_modified).include? 'outline-title')
         doc.attributes['pagenums'] = '' unless (doc.attribute_locked? 'pagenums') || ((doc.instance_variable_get :@attributes_modified).include? 'pagenums')
         #assign_missing_section_ids doc
 
@@ -187,25 +192,22 @@ module Asciidoctor
 
         marked_page_number = page_number
         # NOTE: a new page will already be started (page_number = 2) if the front cover image is a PDF
-        layout_cover_page doc, :front
+        ink_cover_page doc, :front
         has_front_cover = page_number > marked_page_number
-
-        if (use_title_page = doc.doctype == 'book' || (doc.attr? 'title-page'))
-          layout_title_page doc
-          has_title_page = page_number == (has_front_cover ? 2 : 1)
-        end
+        has_title_page = ink_title_page doc if (title_page_on = doc.doctype == 'book' || (doc.attr? 'title-page'))
 
         @page_margin_by_side[:cover] = @page_margin_by_side[:recto] if @media == 'prepress' && page_number == 0
 
         start_new_page unless page&.empty? # rubocop:disable Lint/SafeNavigationWithEmpty
 
-        # NOTE: font must be set before content is written to the main or scratch document
+        # NOTE: the base font must be set before any content is written to the main or scratch document
+        # this method is called inside ink_title_page if the title page is active
         font @theme.base_font_family, size: @root_font_size, style: @theme.base_font_style unless has_title_page
 
-        unless use_title_page
+        unless title_page_on
           body_start_page_number = page_number
           theme_font :heading, level: 1 do
-            layout_general_heading doc, doc.doctitle, align: (@theme.heading_h1_align&.to_sym || :center), level: 1, role: :doctitle
+            ink_general_heading doc, doc.doctitle, align: (@theme.heading_h1_text_align&.to_sym || :center), level: 1, role: :doctitle
           end if doc.header? && !doc.notitle
         end
 
@@ -216,14 +218,14 @@ module Asciidoctor
           if (insert_toc = (doc.attr? 'toc') && !((toc_placement = doc.attr 'toc-placement') == 'macro' || toc_placement == 'preamble') && doc.sections?)
             start_new_page if @ppbook && verso_page?
             add_dest_for_block doc, id: 'toc', y: (at_page_top? ? page_height : nil)
-            allocate_toc doc, toc_num_levels, cursor, use_title_page
+            @toc_extent = allocate_toc doc, toc_num_levels, cursor, title_page_on
           else
             @toc_extent = nil
           end
 
           start_new_page if @ppbook && verso_page? && !(((next_block = doc.blocks[0])&.context == :preamble ? next_block.blocks[0] : next_block)&.option? 'nonfacing')
 
-          if use_title_page
+          if title_page_on
             zero_page_offset = has_front_cover ? 1 : 0
             first_page_offset = has_title_page ? zero_page_offset.next : zero_page_offset
             body_offset = (body_start_page_number = page_number) - 1
@@ -301,26 +303,26 @@ module Asciidoctor
           traverse doc
 
           # NOTE: for a book, these are leftover footnotes; for an article this is everything
-          outdent_section { layout_footnotes doc }
+          outdent_section { ink_footnotes doc }
 
-          if @toc_extent
-            if use_title_page && !insert_toc
-              num_front_matter_pages[0] = @toc_extent.to.page if @theme.running_content_start_at == 'after-toc'
-              num_front_matter_pages[1] = @toc_extent.to.page if @theme.page_numbering_start_at == 'after-toc'
+          if (toc_extent = @toc_extent)
+            if title_page_on && !insert_toc
+              num_front_matter_pages[0] = toc_extent.to.page if @theme.running_content_start_at == 'after-toc'
+              num_front_matter_pages[1] = toc_extent.to.page if @theme.page_numbering_start_at == 'after-toc'
             end
-            toc_page_nums = layout_toc doc, toc_num_levels, @toc_extent.from.page, @toc_extent.from.cursor, num_front_matter_pages[1]
+            toc_page_nums = ink_toc doc, toc_num_levels, toc_extent.from.page, toc_extent.from.cursor, num_front_matter_pages[1]
           else
             toc_page_nums = []
           end
 
           # NOTE: delete orphaned page (a page was created but there was no additional content)
           # QUESTION: should we delete page if document is empty? (leaving no pages?)
-          delete_page if page_count > 1 && page.empty?
+          delete_current_page if page_count > 1 && page.empty?
         end
 
         unless page_count < body_start_page_number
-          layout_running_content :header, doc, num_front_matter_pages, body_start_page_number unless doc.noheader || @theme.header_height.to_f == 0 # rubocop:disable Lint/FloatComparison
-          layout_running_content :footer, doc, num_front_matter_pages, body_start_page_number unless doc.nofooter || @theme.footer_height.to_f == 0 # rubocop:disable Lint/FloatComparison
+          ink_running_content :header, doc, num_front_matter_pages, body_start_page_number unless doc.noheader || @theme.header_height.to_f == 0 # rubocop:disable Lint/FloatComparison
+          ink_running_content :footer, doc, num_front_matter_pages, body_start_page_number unless doc.nofooter || @theme.footer_height.to_f == 0 # rubocop:disable Lint/FloatComparison
         end
 
         add_outline doc, (doc.attr 'outlinelevels', toc_num_levels), toc_page_nums, num_front_matter_pages[1], has_front_cover
@@ -337,7 +339,7 @@ module Asciidoctor
         catalog.data[:ViewerPreferences] = { DisplayDocTitle: true }
 
         stamp_foreground_image doc, has_front_cover
-        layout_cover_page doc, :back
+        ink_cover_page doc, :back
         add_dest_for_top doc
         nil
       end
@@ -402,7 +404,7 @@ module Asciidoctor
         @font_scale = 1
         @font_color = theme.base_font_color
         @text_decoration_width = theme.base_text_decoration_width
-        @base_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_align
+        @base_text_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_text_align
         @base_line_height = theme.base_line_height
         @cjk_line_breaks = doc.attr? 'scripts', 'cjk'
         if (hyphen_lang = doc.attr 'hyphens') &&
@@ -415,6 +417,7 @@ module Asciidoctor
         @text_transform = nil
         @list_numerals = []
         @list_bullets = []
+        @bottom_gutters = [{}]
         @rendered_footnotes = []
         @conum_glyphs = ConumSets[@theme.conum_glyphs || 'circled'] || (@theme.conum_glyphs.split ',').map do |r|
           from, to = r.lstrip.split '-', 2
@@ -460,7 +463,6 @@ module Asciidoctor
       end
 
       def prepare_theme theme
-        theme.base_border_width || 0
         theme.base_font_color ||= '000000'
         theme.base_font_size ||= 12
         theme.base_font_style = theme.base_font_style&.to_sym || :normal
@@ -477,6 +479,9 @@ module Asciidoctor
         theme.list_item_spacing ||= 0
         theme.description_list_term_spacing ||= 0
         theme.description_list_description_indent ||= 0
+        theme.table_border_color ||= (theme.base_border_color || '000000')
+        theme.table_border_width ||= 0.5
+        theme.thematic_break_border_color ||= (theme.base_border_color || '000000')
         theme.image_border_width ||= 0
         theme.code_linenum_font_color ||= '999999'
         theme.callout_list_margin_top_after_code ||= 0
@@ -661,22 +666,23 @@ module Asciidoctor
           title = %(#{title}\n<em class="subtitle">#{subtitle}</em>)
         end
         hlevel = sect.level + 1
-        align = (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym
+        align = (@theme[%(heading_h#{hlevel}_text_align)] || @theme.heading_text_align || @base_text_align).to_sym
         chapterlike = !(part = sectname == 'part') && (sectname == 'chapter' || (sect.document.doctype == 'book' && sect.level == 1))
-        hopts = { align: align, level: hlevel, outdent: !(part || chapterlike) }
+        hidden = sect.option? 'notitle'
+        hopts = { align: align, level: hlevel, part: part, chapterlike: chapterlike, outdent: !(part || chapterlike) }
         if part
           unless @theme.heading_part_break_before == 'auto'
             start_new = true
-            theme_font(:heading, level: hlevel) { start_new_part sect }
+            start_new_part sect
           end
         elsif chapterlike
           if @theme.heading_chapter_break_before != 'auto' ||
               (@theme.heading_part_break_after == 'always' && sect == sect.parent.sections[0])
             start_new = true
-            theme_font(:heading, level: hlevel) { start_new_chapter sect }
+            start_new_chapter sect
           end
         end
-        arrange_section sect, title, hopts unless start_new || at_page_top?
+        arrange_section sect, title, hopts unless hidden || start_new || at_page_top?
         # QUESTION: should we store pdf-page-start, pdf-anchor & pdf-destination in internal map?
         sect.set_attr 'pdf-page-start', (start_pgnum = page_number)
         # QUESTION: should we just assign the section this generated id?
@@ -685,20 +691,20 @@ module Asciidoctor
         add_dest_for_block sect, id: sect_anchor, y: (at_page_top? ? page_height : nil)
         theme_font :heading, level: hlevel do
           if part
-            layout_part_title sect, title, hopts
+            ink_part_title sect, title, hopts
           elsif chapterlike
-            layout_chapter_title sect, title, hopts unless sect.special && (sect.option? 'untitled')
+            ink_chapter_title sect, title, hopts
           else
-            layout_general_heading sect, title, hopts
+            ink_general_heading sect, title, hopts
           end
-        end
+        end unless hidden
 
         if index_section
           outdent_section { convert_index_section sect }
         else
           traverse sect
         end
-        outdent_section { layout_footnotes sect } if chapterlike
+        outdent_section { ink_footnotes sect } if chapterlike
         sect.set_attr 'pdf-page-end', page_number
       end
 
@@ -719,7 +725,7 @@ module Asciidoctor
       end
 
       # QUESTION: if a footnote ref appears in a separate chapter, should the footnote def be duplicated?
-      def layout_footnotes node
+      def ink_footnotes node
         return if (fns = (doc = node.document).footnotes - @rendered_footnotes).empty?
         theme_margin :block, :bottom if node.context == :document || node == node.document.blocks[-1]
         theme_margin :footnotes, :top
@@ -728,7 +734,7 @@ module Asciidoctor
             move_down delta
           end
           theme_font :footnotes do
-            (title = doc.attr 'footnotes-title') && (layout_caption title, category: :footnotes)
+            (title = doc.attr 'footnotes-title') && (ink_caption title, category: :footnotes)
             item_spacing = @theme.footnotes_item_spacing
             index_offset = @rendered_footnotes.length
             sect_xreftext = node.context == :section && (node.xreftext node.document.attr 'xrefstyle')
@@ -738,7 +744,7 @@ module Asciidoctor
                 fn.singleton_class.send :attr_accessor, :label unless fn.respond_to? :label=
                 fn.label = %(#{label} - #{sect_xreftext})
               end
-              layout_prose %(<a id="_footnotedef_#{index}">#{DummyText}</a>[<a anchor="_footnoteref_#{index}">#{label}</a>] #{fn.text}), margin_bottom: item_spacing, hyphenate: true
+              ink_prose %(<a id="_footnotedef_#{index}">#{DummyText}</a>[<a anchor="_footnoteref_#{index}">#{label}</a>] #{fn.text}), margin_bottom: item_spacing, hyphenate: true
             end
             @rendered_footnotes += fns if extent
           end
@@ -750,11 +756,11 @@ module Asciidoctor
         add_dest_for_block node if node.id
         hlevel = node.level.next
         unless (align = resolve_alignment_from_role node.roles)
-          align = (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym
+          align = (@theme[%(heading_h#{hlevel}_text_align)] || @theme.heading_text_align || @base_text_align).to_sym
         end
         # QUESTION: should we decouple styles from section titles?
         theme_font :heading, level: hlevel do
-          layout_general_heading node, node.title, align: align, level: hlevel, outdent: (node.parent.context == :section)
+          ink_general_heading node, node.title, align: align, level: hlevel, outdent: (node.parent.context == :section)
         end
       end
 
@@ -763,10 +769,10 @@ module Asciidoctor
         outdent_section do
           pad_box @theme.abstract_padding do
             theme_font :abstract_title do
-              layout_prose node.title, align: (@theme.abstract_title_align || @base_align).to_sym, margin_top: @theme.heading_margin_top, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
+              ink_prose node.title, align: (@theme.abstract_title_text_align || @base_text_align).to_sym, margin_top: @theme.heading_margin_top, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
             end if node.title?
             theme_font :abstract do
-              prose_opts = { align: (@theme.abstract_align || @base_align).to_sym, hyphenate: true }
+              prose_opts = { align: (@theme.abstract_text_align || @base_text_align).to_sym, hyphenate: true }
               if (text_indent = @theme.prose_text_indent) > 0
                 prose_opts[:indent_paragraphs] = text_indent
               end
@@ -785,7 +791,7 @@ module Asciidoctor
                   if child.context == :paragraph
                     child.document.playback_attributes child.attributes
                     prose_opts[:margin_bottom] = 0 if child == last_block
-                    layout_prose child.content, ((align = resolve_alignment_from_role child.roles) ? (prose_opts.merge align: align) : prose_opts.dup)
+                    ink_prose child.content, ((align = resolve_alignment_from_role child.roles) ? (prose_opts.merge align: align) : prose_opts.dup)
                     prose_opts.delete :first_line_options
                     prose_opts.delete :margin_bottom
                   else
@@ -797,7 +803,7 @@ module Asciidoctor
                 if (align = resolve_alignment_from_role node.roles)
                   prose_opts[:align] = align
                 end
-                layout_prose string, (prose_opts.merge margin_bottom: 0)
+                ink_prose string, (prose_opts.merge margin_bottom: 0)
               end
             end
           end
@@ -809,7 +815,7 @@ module Asciidoctor
       def convert_preamble node
         # FIXME: core should not be promoting paragraph to preamble if there are no sections
         if node.blocks? && (first_block = node.blocks[0]).context == :paragraph && node.document.sections? && !first_block.role?
-          first_block.add_role 'lead'
+          first_block.role = 'lead'
         end
         traverse node
         theme_margin :block, :bottom, (next_enclosed_block node)
@@ -832,13 +838,17 @@ module Asciidoctor
 
         # TODO: check if we're within one line of the bottom of the page
         # and advance to the next page if so (similar to logic for section titles)
-        layout_caption node, labeled: false if node.title?
+        ink_caption node, labeled: false if node.title?
+
+        if (bottom_gutter = @bottom_gutters[-1][node])
+          prose_opts[:bottom_gutter] = bottom_gutter
+        end
 
         if roles.empty?
-          layout_prose node.content, prose_opts
+          ink_prose node.content, prose_opts
         else
           theme_font_cascade (roles.map {|role| %(role_#{role}).to_sym }) do
-            layout_prose node.content, prose_opts
+            ink_prose node.content, prose_opts
           end
         end
 
@@ -852,7 +862,7 @@ module Asciidoctor
 
       def convert_admonition node
         type = node.attr 'name'
-        label_align = @theme.admonition_label_align&.to_sym || :center
+        label_align = @theme.admonition_label_text_align&.to_sym || :center
         # TODO: allow vertical_align to be a number
         if (label_valign = @theme.admonition_label_vertical_align&.to_sym || :middle) == :middle
           label_valign = :center
@@ -861,18 +871,21 @@ module Asciidoctor
           label_min_width = label_min_width.to_f
         end
         if (doc = node.document).attr? 'icons'
-          if (doc.attr 'icons') == 'font' && !(node.attr? 'icon')
+          if !(has_icon = node.attr? 'icon') && (doc.attr 'icons') == 'font'
             icons = 'font'
             label_text = type.to_sym
             icon_data = admonition_icon_data label_text
             icon_size = icon_data[:size] || 24
             label_width = label_min_width || (icon_size * 1.5)
-          elsif (icon_path = resolve_icon_image_path node, type) && (::File.readable? icon_path)
+          elsif (icon_path = has_icon || !(icon_path = (@theme[%(admonition_icon_#{type})] || {})[:image]) ?
+              (resolve_icon_image_path node, type) :
+              (ThemeLoader.resolve_theme_asset (apply_subs_discretely doc, icon_path, subs: [:attributes]), @themesdir)) &&
+              (::File.readable? icon_path)
             icons = true
             # TODO: introduce @theme.admonition_image_width? or use size key from admonition_icon_<name>?
             label_width = label_min_width || 36.0
           else
-            log :warn, %(admonition icon not found or not readable: #{icon_path || (resolve_icon_image_path node, type, false)})
+            log :warn, %(admonition icon image#{has_icon ? '' : ' for ' + type.upcase} not found or not readable: #{icon_path || (resolve_icon_image_path node, type, false)})
           end
         end
         unless icons
@@ -883,20 +896,16 @@ module Asciidoctor
             label_width = label_min_width if label_min_width && label_min_width > label_width
           end
         end
-        unless ::Array === (cpad = @theme.admonition_padding || 0)
-          cpad = ::Array.new 4, cpad
-        end
-        unless ::Array === (lpad = @theme.admonition_label_padding || cpad)
-          lpad = ::Array.new 4, lpad
-        end
+        cpad = expand_padding_value @theme.admonition_padding
+        lpad = (lpad = @theme.admonition_label_padding) ? (expand_padding_value lpad) : cpad
         arrange_block node do |extent|
           add_dest_for_block node if node.id
           theme_fill_and_stroke_block :admonition, extent if extent
           pad_box [0, cpad[1], 0, lpad[3]] do
             if extent
               label_height = extent.single_page_height || cursor
-              if (rule_color = @theme.admonition_column_rule_color) &&
-                  (rule_width = @theme.admonition_column_rule_width || @theme.base_border_width) && rule_width > 0
+              if (rule_width = @theme.admonition_column_rule_width || 0) > 0 &&
+                  (rule_color = @theme.admonition_column_rule_color || @theme.base_border_color)
                 rule_style = @theme.admonition_column_rule_style&.to_sym || :solid
                 float do
                   extent.each_page do |first_page, last_page|
@@ -945,7 +954,7 @@ module Asciidoctor
                           log :warn, %(problem encountered in image: #{icon_path}; #{icon_warning})
                         end unless scratch?
                       rescue
-                        log :warn, %(could not embed admonition icon: #{icon_path}; #{$!.message})
+                        log :warn, %(could not embed admonition icon image: #{icon_path}; #{$!.message})
                         icons = nil
                       end
                     else
@@ -959,7 +968,7 @@ module Asciidoctor
                         end
                         embed_image image_obj, image_info, width: icon_width, position: label_align, vposition: label_valign
                       rescue
-                        log :warn, %(could not embed admonition icon: #{icon_path}; #{$!.message})
+                        log :warn, %(could not embed admonition icon image: #{icon_path}; #{$!.message})
                         icons = nil
                       end
                     end
@@ -987,7 +996,7 @@ module Asciidoctor
                         end
                       end
                       @text_transform = nil # already applied to label
-                      layout_prose label_text,
+                      ink_prose label_text,
                         align: label_align,
                         valign: label_valign,
                         line_height: 1,
@@ -1000,8 +1009,8 @@ module Asciidoctor
                 end
               end
             end
-            pad_box [cpad[0], 0, cpad[2], label_width + lpad[1] + cpad[3]] do
-              layout_caption node, category: :admonition, labeled: false if node.title?
+            pad_box [cpad[0], 0, cpad[2], label_width + lpad[1] + cpad[3]], node do
+              ink_caption node, category: :admonition, labeled: false if node.title?
               theme_font :admonition do
                 traverse node
               end
@@ -1018,7 +1027,7 @@ module Asciidoctor
           tare_first_page_content_stream do
             theme_fill_and_stroke_block :example, extent, caption_node: node
           end
-          pad_box @theme.example_padding do
+          pad_box @theme.example_padding, node do
             theme_font :example do
               traverse node
             end
@@ -1035,13 +1044,13 @@ module Asciidoctor
           arrange_block node do
             add_dest_for_block node if id
             tare_first_page_content_stream do
-              node.context == :example ? (layout_caption %(\u25bc #{node.title})) : (layout_caption node, labeled: false)
+              node.context == :example ? (ink_caption %(\u25bc #{node.title})) : (ink_caption node, labeled: false)
             end if has_title
             traverse node
           end
         else
           add_dest_for_block node if id
-          node.context == :example ? (layout_caption %(\u25bc #{node.title})) : (layout_caption node, labeled: false) if has_title
+          node.context == :example ? (ink_caption %(\u25bc #{node.title})) : (ink_caption node, labeled: false) if has_title
           traverse node
         end
       end
@@ -1050,11 +1059,18 @@ module Asciidoctor
         category = node.context == :quote ? :quote : :verse
         # NOTE: b_width and b_left_width are mutually exclusive
         if (b_left_width = @theme[%(#{category}_border_left_width)]) && b_left_width > 0
-          b_color = @theme[%(#{category}_border_color)]
+          b_color = @theme[%(#{category}_border_color)] || @theme.base_border_color
         else
           b_left_width = nil
           b_width = nil if (b_width = @theme[%(#{category}_border_width)]) == 0
         end
+        if (attribution = (node.attr? 'attribution') && (node.attr 'attribution'))
+          # NOTE: temporary workaround to allow bare & to be used without having to wrap value in single quotes
+          attribution = escape_amp attribution if attribution.include? '&'
+          if (citetitle = node.attr 'citetitle') && (citetitle.include? '&')
+            citetitle = escape_amp citetitle
+          end
+        end
         arrange_block node do |extent|
           add_dest_for_block node if node.id
           tare_first_page_content_stream do
@@ -1072,27 +1088,25 @@ module Asciidoctor
               end
             end
           end
-          pad_box @theme[%(#{category}_padding)] do
+          pad_box @theme[%(#{category}_padding)], (attribution ? nil : node) do
             theme_font category do
               if category == :quote
                 traverse node
               else # :verse
                 content = guard_indentation node.content
-                layout_prose content, normalize: false, align: :left, hyphenate: true, margin_bottom: 0
+                ink_prose content,
+                  normalize: false,
+                  align: :left,
+                  hyphenate: true,
+                  margin_bottom: 0,
+                  bottom_gutter: (attribution ? nil : @bottom_gutters[-1][node])
               end
             end
-            if node.attr? 'attribution'
+            if attribution
               margin_bottom @theme.block_margin_bottom
               theme_font %(#{category}_cite) do
-                # NOTE: temporary workaround to allow bare & to be used without having to wrap value in single quotes
-                attribution = node.attr 'attribution'
-                attribution = escape_amp attribution if attribution.include? '&'
-                attribution_parts = [attribution]
-                if (citetitle = node.attr 'citetitle')
-                  citetitle = escape_amp citetitle if citetitle.include? '&'
-                  attribution_parts << citetitle
-                end
-                layout_prose %(#{EmDash} #{attribution_parts.join ', '}), align: :left, normalize: false, margin_bottom: 0
+                attribution_parts = citetitle ? [attribution, citetitle] : [attribution]
+                ink_prose %(#{EmDash} #{attribution_parts.join ', '}), align: :left, normalize: false, margin_bottom: 0
               end
             end
           end
@@ -1107,10 +1121,10 @@ module Asciidoctor
         arrange_block node do |extent|
           add_dest_for_block node if node.id
           theme_fill_and_stroke_block :sidebar, extent if extent
-          pad_box @theme.sidebar_padding do
+          pad_box @theme.sidebar_padding, node do
             theme_font :sidebar_title do
               # QUESTION: should we allow margins of sidebar title to be customized?
-              layout_prose node.title, align: (@theme.sidebar_title_align || @theme.heading_align || @base_align).to_sym, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
+              ink_prose node.title, align: (@theme.sidebar_title_text_align || @theme.heading_text_align || @base_text_align).to_sym, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
             end if node.title?
             theme_font :sidebar do
               traverse node
@@ -1149,7 +1163,7 @@ module Asciidoctor
           marker_width = rendered_width_of_string %(#{marker = conum_glyph index}x)
           float do
             bounding_box [0, cursor], width: marker_width do
-              layout_prose marker, align: :center, inline_format: false, margin: 0
+              ink_prose marker, align: :center, inline_format: false, margin: 0
             end
           end
         end
@@ -1233,7 +1247,7 @@ module Asciidoctor
           max_term_width += (term_padding[1] + term_padding[3])
           term_column_width = [max_term_width, bounds.width * 0.5].min
           table table_data, position: :left, cell_style: { border_width: 0 }, column_widths: [term_column_width] do
-            @pdf.layout_table_caption node if node.title?
+            @pdf.ink_table_caption node if node.title?
           end
           theme_margin :prose, :bottom, (next_enclosed_block actual_node) #unless actual_node.nested?
         when 'qanda'
@@ -1243,7 +1257,7 @@ module Asciidoctor
         else
           # TODO: check if we're within one line of the bottom of the page
           # and advance to the next page if so (similar to logic for section titles)
-          layout_caption node, category: :description_list, labeled: false if node.title?
+          ink_caption node, category: :description_list, labeled: false if node.title?
 
           term_spacing = @theme.description_list_term_spacing
           term_height = theme_font(:description_list_term) { height_of_typeset_text 'A' }
@@ -1255,8 +1269,8 @@ module Asciidoctor
                 term_font_styles = nil
               end
               terms.each_with_index do |term, idx|
-                # QUESTION: should we pass down styles in other calls to layout_prose
-                layout_prose term.text, margin_top: (idx > 0 ? term_spacing : 0), margin_bottom: 0, align: :left, normalize_line_height: true, styles: term_font_styles
+                # QUESTION: should we pass down styles in other calls to ink_prose
+                ink_prose term.text, margin_top: (idx > 0 ? term_spacing : 0), margin_bottom: 0, align: :left, normalize_line_height: true, styles: term_font_styles
               end
             end
             indent @theme.description_list_description_indent do
@@ -1343,7 +1357,7 @@ module Asciidoctor
       def convert_list node
         # TODO: check if we're within one line of the bottom of the page
         # and advance to the next page if so (similar to logic for section titles)
-        layout_caption node, category: :list, labeled: false if node.title?
+        ink_caption node, category: :list, labeled: false if node.title?
 
         opts = {}
         if (align = resolve_alignment_from_role node.roles)
@@ -1440,7 +1454,7 @@ module Asciidoctor
             float do
               advance_page if @media == 'prepress' && cursor < marker_height
               flow_bounding_box position: start_position, width: marker_width do
-                layout_prose marker,
+                ink_prose marker,
                   align: :right,
                   character_spacing: -0.5,
                   color: marker_style[:font_color],
@@ -1468,16 +1482,16 @@ module Asciidoctor
       def traverse_list_item node, list_type, opts = {}
         if list_type == :dlist # qanda
           terms, desc = node
-          terms.each {|term| layout_prose %(<em>#{term.text}</em>), (opts.merge margin_bottom: @theme.description_list_term_spacing) }
+          terms.each {|term| ink_prose %(<em>#{term.text}</em>), (opts.merge margin_bottom: @theme.description_list_term_spacing) }
           if desc
-            layout_prose desc.text, (opts.merge hyphenate: true) if desc.text?
+            ink_prose desc.text, (opts.merge hyphenate: true) if desc.text?
             traverse desc
           end
         else
           if (primary_text = node.text).nil_or_empty?
-            layout_prose DummyText, opts unless node.blocks?
+            ink_prose DummyText, opts unless node.blocks?
           else
-            layout_prose primary_text, (opts.merge hyphenate: true)
+            ink_prose primary_text, (opts.merge hyphenate: true)
           end
           traverse node
         end
@@ -1498,24 +1512,33 @@ module Asciidoctor
         elsif (image_path = resolve_image_path node, target, image_format, (opts.fetch :relative_to_imagesdir, true))
           if image_format == 'pdf'
             if ::File.readable? image_path
-              if (id = node.id)
+              if (replace = page.empty?) && ((parent = node.parent).attr? 'pdf-page-start', page_number) && (parent.attr? 'pdf-anchor')
+                replace_parent = parent
+              end
+              if (id = node.id) || replace_parent
                 add_dest_block = proc do
-                  node.set_attr 'pdf-destination', (node_dest = dest_top)
-                  add_dest id, node_dest
+                  node_dest = dest_top
+                  if id
+                    node.set_attr 'pdf-destination', node_dest
+                    add_dest id, node_dest
+                  end
+                  if replace_parent
+                    replace_parent.set_attr 'pdf-destination', node_dest
+                    add_dest (replace_parent.attr 'pdf-anchor'), node_dest
+                  end
                 end
               end
               # NOTE: import_page automatically advances to next page afterwards
-              # QUESTION: should we add destination to top of imported page?
               if (pgnums = node.attr 'pages')
                 (resolve_pagenums pgnums).each_with_index do |pgnum, idx|
                   if idx == 0
-                    import_page image_path, page: pgnum, replace: page.empty?, &add_dest_block
+                    import_page image_path, page: pgnum, replace: replace, &add_dest_block
                   else
                     import_page image_path, page: pgnum, replace: true
                   end
                 end
               else
-                import_page image_path, page: [(node.attr 'page', nil, 1).to_i, 1].max, replace: page.empty?, &add_dest_block
+                import_page image_path, page: [(node.attr 'page', nil, 1).to_i, 1].max, replace: replace, &add_dest_block
               end
               return
             else
@@ -1532,14 +1555,16 @@ module Asciidoctor
 
         alignment = (alignment = node.attr 'align') ?
           ((BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left) :
-          (resolve_alignment_from_role node.roles) || (@theme.image_align&.to_sym || :left)
+          (resolve_alignment_from_role node.roles) || @theme.image_align&.to_sym || :left
         # TODO: support cover (aka canvas) image layout using "canvas" (or "cover") role
         width = resolve_explicit_width node.attributes, bounds_width: (available_w = bounds.width), support_vw: true, use_fallback: true, constrain_to_bounds: true
         # TODO: add `to_pt page_width` method to ViewportWidth type
         width = (width.to_f / 100) * page_width if ViewportWidth === width
 
+        caption_end = @theme.image_caption_end&.to_sym || :bottom
+        caption_max_width = @theme.image_caption_max_width
         # NOTE: if width is not set explicitly and max-width is fit-content, caption height may not be accurate
-        caption_h = node.title? ? (layout_caption node, category: :image, side: :bottom, block_align: alignment, block_width: width, max_width: @theme.image_caption_max_width, dry_run: true, force_top_margin: true) : 0
+        caption_h = node.title? ? (ink_caption node, category: :image, end: caption_end, block_align: alignment, block_width: width, max_width: caption_max_width, dry_run: true, force_top_margin: caption_end == :bottom) : 0
 
         align_to_page = node.option? 'align-to-page'
         pinned = opts[:pinned]
@@ -1575,14 +1600,14 @@ module Asciidoctor
                 end
                 rendered_w = (svg_obj.resize height: (rendered_h = available_h)).output_width if rendered_h > available_h
               end
-              image_y = y
-              image_cursor = cursor
               add_dest_for_block node if node.id
               # NOTE: workaround to fix Prawn not adding fill and stroke commands on page that only has an image;
               # breakage occurs when running content (stamps) are added to page
               update_colors if graphic_state.color_space.empty?
-              # NOTE: cursor advances automatically
-              svg_obj.draw
+              ink_caption node, category: :image, end: :top, block_align: alignment, block_width: rendered_w, max_width: caption_max_width if caption_end == :top && node.title?
+              image_y = y
+              image_cursor = cursor
+              svg_obj.draw # NOTE: cursor advances automatically
               svg_obj.document.warnings.each do |img_warning|
                 log :warn, %(problem encountered in image: #{image_path}; #{img_warning})
               end unless scratch?
@@ -1606,12 +1631,13 @@ module Asciidoctor
                 end
                 rendered_w, rendered_h = image_info.calc_image_dimensions height: available_h if rendered_h > available_h
               end
-              image_y = y
-              image_cursor = cursor
               add_dest_for_block node if node.id
               # NOTE: workaround to fix Prawn not adding fill and stroke commands on page that only has an image;
               # breakage occurs when running content (stamps) are added to page
               update_colors if graphic_state.color_space.empty?
+              ink_caption node, category: :image, end: :top, block_align: alignment, block_width: rendered_w, max_width: caption_max_width if caption_end == :top && node.title?
+              image_y = y
+              image_cursor = cursor
               # NOTE: specify both width and height to avoid recalculation
               embed_image image_obj, image_info, width: rendered_w, height: rendered_h, position: alignment
               draw_image_border image_cursor, rendered_w, rendered_h, alignment unless node.role? && (node.has_role? 'noborder')
@@ -1622,7 +1648,7 @@ module Asciidoctor
               move_down rendered_h if y == image_y
             end
           end
-          layout_caption node, category: :image, side: :bottom, block_align: alignment, block_width: rendered_w, max_width: @theme.image_caption_max_width if node.title?
+          ink_caption node, category: :image, end: :bottom, block_align: alignment, block_width: rendered_w, max_width: caption_max_width if caption_end == :bottom && node.title?
           theme_margin :block, :bottom, (next_enclosed_block node) unless pinned
         rescue => e
           raise if ::StopIteration === e
@@ -1631,7 +1657,7 @@ module Asciidoctor
       end
 
       def draw_image_border top, w, h, alignment
-        if @theme.image_border_width > 0 && @theme.image_border_color
+        if (Array @theme.image_border_width).any? {|it| it&.> 0 } && (@theme.image_border_color || @theme.base_border_color)
           if (@theme.image_border_fit || 'content') == 'auto'
             bb_width = bounds.width
           elsif alignment == :center
@@ -1662,9 +1688,9 @@ module Asciidoctor
           alignment = (alignment = node.attr 'align') ?
             ((BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left) :
             (resolve_alignment_from_role node.roles) || (@theme.image_align&.to_sym || :left)
-          layout_prose alt_text_template % alt_text_vars, align: alignment, margin: 0, normalize: false, single_line: true
+          ink_prose alt_text_template % alt_text_vars, align: alignment, margin: 0, normalize: false, single_line: true
         end
-        layout_caption node, category: :image, side: :bottom if node.title?
+        ink_caption node, category: :image, end: :bottom if node.title?
         theme_margin :block, :bottom, (next_enclosed_block node) unless opts[:pinned]
         nil
       end
@@ -1673,8 +1699,8 @@ module Asciidoctor
         add_dest_for_block node if node.id
         audio_path = node.media_uri node.attr 'target'
         play_symbol = (node.document.attr? 'icons', 'font') ? %(<font name="fas">#{(icon_font_data 'fas').unicode 'play'}</font>) : RightPointer
-        layout_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{audio_path}">#{audio_path}</a> <em>(audio)</em>), normalize: false, margin: 0, single_line: true
-        layout_caption node, labeled: false, side: :bottom if node.title?
+        ink_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{audio_path}">#{audio_path}</a> <em>(audio)</em>), normalize: false, margin: 0, single_line: true
+        ink_caption node, labeled: false, end: :bottom if node.title?
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
@@ -1701,8 +1727,8 @@ module Asciidoctor
         if poster.nil_or_empty?
           add_dest_for_block node if node.id
           play_symbol = (node.document.attr? 'icons', 'font') ? %(<font name="fas">#{(icon_font_data 'fas').unicode 'play'}</font>) : RightPointer
-          layout_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{video_path}">#{video_path}</a> <em>(#{type})</em>), normalize: false, margin: 0, single_line: true
-          layout_caption node, labeled: false, side: :bottom if node.title?
+          ink_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{video_path}">#{video_path}</a> <em>(#{type})</em>), normalize: false, margin: 0, single_line: true
+          ink_caption node, labeled: false, end: :bottom if node.title?
           theme_margin :block, :bottom, (next_enclosed_block node)
         else
           original_attributes = node.attributes.dup
@@ -1717,7 +1743,8 @@ module Asciidoctor
 
       # QUESTION: can we avoid arranging fragments multiple times (conums & autofit) by eagerly preparing arranger?
       def convert_listing_or_literal node
-        wrap_ext = source_chunks = bg_color_override = font_color_override = adjusted_font_size = nil
+        extensions = []
+        source_chunks = bg_color_override = font_color_override = adjusted_font_size = nil
         theme_font :code do
           # HACK: disable built-in syntax highlighter; must be done before calling node.content!
           if node.style == 'source' && (highlighter = (syntax_hl = node.document.syntax_highlighter)&.highlight? && syntax_hl.name)
@@ -1797,7 +1824,7 @@ module Asciidoctor
               if (node.option? 'linenums') || (node.attr? 'linenums')
                 linenums = (node.attr 'start', 1).to_i
                 postprocess = true
-                wrap_ext = FormattedText::SourceWrap
+                extensions << FormattedText::SourceWrap
               elsif conum_mapping || highlight_lines
                 postprocess = true
               end
@@ -1814,7 +1841,7 @@ module Asciidoctor
             else
               if (node.option? 'linenums') || (node.attr? 'linenums')
                 formatter_opts = { line_numbers: true, start_line: (node.attr 'start', 1).to_i }
-                wrap_ext = FormattedText::SourceWrap
+                extensions << FormattedText::SourceWrap
               else
                 formatter_opts = {}
               end
@@ -1848,14 +1875,13 @@ module Asciidoctor
           tare_first_page_content_stream do
             theme_fill_and_stroke_block :code, extent, background_color: bg_color_override, caption_node: node
           end
-          pad_box @theme.code_padding do
+          pad_box @theme.code_padding, node do
             theme_font :code do
-              ::Prawn::Text::Formatted::Box.extensions << wrap_ext if wrap_ext
               typeset_formatted_text source_chunks, (calc_line_metrics @base_line_height),
                 color: (font_color_override || @theme.code_font_color || @font_color),
-                size: adjusted_font_size
-            ensure
-              ::Prawn::Text::Formatted::Box.extensions.pop if wrap_ext
+                size: adjusted_font_size,
+                bottom_gutter: @bottom_gutters[-1][node],
+                extensions: extensions.empty? ? nil : extensions
             end
           end
         end
@@ -2001,6 +2027,7 @@ module Asciidoctor
 
         base_header_cell_data = nil
         header_cell_line_metrics = nil
+        body_cell_padding = expand_padding_value theme.table_cell_padding
 
         table_data = []
         theme_font :table do
@@ -2015,7 +2042,7 @@ module Asciidoctor
             table_header_size = head_rows.size
             head_font_info = font_info
             head_line_metrics = calc_line_metrics theme.table_head_line_height || theme.table_cell_line_height || @base_line_height
-            head_cell_padding = expand_padding_value theme.table_head_cell_padding || theme.table_cell_padding
+            head_cell_padding = ((head_cell_padding = theme.table_head_cell_padding) ? (expand_padding_value head_cell_padding) : body_cell_padding).dup
             head_cell_padding[0] += head_line_metrics.padding_top
             head_cell_padding[2] += head_line_metrics.padding_bottom
             # QUESTION: why doesn't text transform inherit from table?
@@ -2054,7 +2081,6 @@ module Asciidoctor
             text_color: @font_color,
           }
           body_cell_line_metrics = calc_line_metrics (theme.table_cell_line_height || @base_line_height)
-          body_cell_padding = expand_padding_value theme.table_cell_padding
           (body_rows + node.rows[:foot]).each do |row|
             table_data << (row.map do |cell|
               cell_data = base_cell_data.merge \
@@ -2121,7 +2147,7 @@ module Asciidoctor
                 end
                 # NOTE: line metrics get applied when AsciiDoc content is converted
                 cell_line_metrics = nil
-                asciidoc_cell = ::Prawn::Table::Cell::AsciiDoc.new self, (cell_data.merge content: cell.inner_document, padding: body_cell_padding.dup)
+                asciidoc_cell = ::Prawn::Table::Cell::AsciiDoc.new self, (cell_data.merge content: cell.inner_document, padding: body_cell_padding)
                 cell_data = { content: asciidoc_cell }
               end
               if cell_line_metrics
@@ -2159,45 +2185,36 @@ module Asciidoctor
           end
         end
 
-        # NOTE: Prawn aborts if table data is empty, so ensure there's at least one row
+        # NOTE: Prawn crashes if table data is empty, so ensure there's at least one row
         if table_data.empty?
           log(:warn) { message_with_context 'no rows found in table', source_location: node.source_location }
           table_data << ::Array.new([node.columns.size, 1].max) { { content: '' } }
         end
 
-        border_width = {}
-        table_border_color = theme.table_border_color || ((Array theme.table_grid_color).size == 2 ? nil : theme.table_grid_color) || theme.base_border_color
-        table_border_style = theme.table_border_style&.to_sym || :solid
-        table_border_width = theme.table_border_width
-        if table_header_size
-          head_border_bottom_color = theme.table_head_border_bottom_color || table_border_color
-          head_border_bottom_style = (theme.table_head_border_bottom_style || table_border_style).to_sym
-          head_border_bottom_width = theme.table_head_border_bottom_width || table_border_width
-        end
-        [:top, :bottom, :left, :right].each {|edge| border_width[edge] = table_border_width }
+        rect_side_names = [:top, :right, :bottom, :left]
+        grid_axis_names = [:rows, :cols]
+        border_color = (rect_side_names.zip expand_rect_values theme.table_border_color, 'transparent').to_h
+        border_style = (rect_side_names.zip (expand_rect_values theme.table_border_style, :solid).map(&:to_sym)).to_h
+        border_width = (rect_side_names.zip expand_rect_values theme.table_border_width, 0).to_h
+        grid_color = (grid_axis_names.zip expand_grid_values (theme.table_grid_color || [border_color[:top], border_color[:left]]), 'transparent').to_h
+        grid_style = (grid_axis_names.zip (expand_grid_values (theme.table_grid_style || [border_style[:top], border_style[:left]]), :solid).map(&:to_sym)).to_h
+        grid_width = (grid_axis_names.zip expand_grid_values (theme.table_grid_width || [border_width[:top], border_width[:left]]), 0).to_h
 
-        table_grid_color = theme.table_grid_color || table_border_color
-        if ::Array === (table_grid_style = theme.table_grid_style || table_border_style)
-          table_grid_style = table_grid_style.map(&:to_sym)
-        else
-          table_grid_style = [table_grid_style.to_sym]
-        end
-        if ::Array === (table_grid_width = theme.table_grid_width || theme.table_border_width)
-          border_width[:rows] = table_grid_width[0]
-          border_width[:cols] = table_grid_width[1]
-        else
-          [:cols, :rows].each {|edge| border_width[edge] = table_grid_width }
+        if table_header_size
+          head_border_bottom_color = theme.table_head_border_bottom_color || grid_color[:rows]
+          head_border_bottom_style = theme.table_head_border_bottom_style&.to_sym || grid_style[:rows]
+          head_border_bottom_width = theme.table_head_border_bottom_width || (grid_width[:rows] * 2.5)
         end
 
         case (grid = node.attr 'grid', 'all', 'table-grid')
         when 'all'
           # keep inner borders
         when 'cols'
-          border_width[:rows] = 0
+          grid_width[:rows] = 0
         when 'rows'
-          border_width[:cols] = 0
+          grid_width[:cols] = 0
         else # none
-          border_width[:rows] = border_width[:cols] = 0
+          grid_width[:rows] = grid_width[:cols] = 0
         end
 
         case (frame = node.attr 'frame', 'all', 'table-frame')
@@ -2227,20 +2244,15 @@ module Asciidoctor
           alignment = theme.table_align&.to_sym || :left
         end
 
-        caption_side = theme.table_caption_side&.to_sym || :top
+        caption_end = theme.table_caption_end&.to_sym || :top
         caption_max_width = theme.table_caption_max_width || 'fit-content'
 
         table_settings = {
           header: table_header_size,
           # NOTE: position is handled by this method
           position: :left,
-          cell_style: {
-            # NOTE: the border color and style of the outer frame is set later
-            border_color: table_grid_color,
-            border_lines: table_grid_style,
-            # NOTE: the border width is set later
-            border_width: 0,
-          },
+          # NOTE: the border color, style, and width of the outer frame is set in the table callback block
+          cell_style: { border_color: grid_color.values, border_lines: grid_style.values, border_width: grid_width.values },
           width: table_width,
           column_widths: column_widths,
         }
@@ -2261,7 +2273,7 @@ module Asciidoctor
         table table_data, table_settings do
           # NOTE: call width to capture resolved table width
           table_width = width
-          @pdf.layout_table_caption node, alignment, table_width, caption_max_width if node.title? && caption_side == :top
+          @pdf.ink_table_caption node, alignment, table_width, caption_max_width if node.title? && caption_end == :top
           # NOTE: align using padding instead of bounding_box as prawn-table does
           # using a bounding_box across pages mangles the margin box of subsequent pages
           if alignment != :left && table_width != (this_bounds = @pdf.bounds).width
@@ -2282,7 +2294,7 @@ module Asciidoctor
             end if table_header_size
           else
             # apply the grid setting first across all cells
-            cells.border_width = [border_width[:rows], border_width[:cols], border_width[:rows], border_width[:cols]]
+            cells.border_width = [grid_width[:rows], grid_width[:cols], grid_width[:rows], grid_width[:cols]]
 
             if table_header_size
               (rows table_header_size - 1).tap do |r|
@@ -2299,19 +2311,19 @@ module Asciidoctor
 
             # top edge of table
             (rows 0).tap do |r|
-              r.border_top_color, r.border_top_line, r.border_top_width = table_border_color, table_border_style, border_width[:top]
+              r.border_top_color, r.border_top_line, r.border_top_width = border_color[:top], border_style[:top], border_width[:top]
             end
             # right edge of table
             (columns num_cols - 1).tap do |r|
-              r.border_right_color, r.border_right_line, r.border_right_width = table_border_color, table_border_style, border_width[:right]
+              r.border_right_color, r.border_right_line, r.border_right_width = border_color[:right], border_style[:right], border_width[:right]
             end
             # bottom edge of table
             (rows num_rows - 1).tap do |r|
-              r.border_bottom_color, r.border_bottom_line, r.border_bottom_width = table_border_color, table_border_style, border_width[:bottom]
+              r.border_bottom_color, r.border_bottom_line, r.border_bottom_width = border_color[:bottom], border_style[:bottom], border_width[:bottom]
             end
             # left edge of table
             (columns 0).tap do |r|
-              r.border_left_color, r.border_left_line, r.border_left_width = table_border_color, table_border_style, border_width[:left]
+              r.border_left_color, r.border_left_line, r.border_left_width = border_color[:left], border_style[:left], border_width[:left]
             end
           end
 
@@ -2334,7 +2346,7 @@ module Asciidoctor
           bounds.subtract_left_padding left_padding
           bounds.subtract_right_padding right_padding if right_padding
         end
-        layout_table_caption node, alignment, table_width, caption_max_width, caption_side if node.title? && caption_side == :bottom
+        ink_table_caption node, alignment, table_width, caption_max_width, caption_end if node.title? && caption_end == :bottom
         theme_margin :block, :bottom, (next_enclosed_block node)
       rescue ::Prawn::Errors::CannotFit
         log :error, (message_with_context 'cannot fit contents of table cell into specified column width', source_location: node.source_location)
@@ -2342,12 +2354,14 @@ module Asciidoctor
 
       def convert_thematic_break node
         theme_margin :thematic_break, :top
-        stroke_horizontal_rule @theme.thematic_break_border_color, line_width: @theme.thematic_break_border_width, line_style: (@theme.thematic_break_border_style&.to_sym || :solid)
+        stroke_horizontal_rule @theme.thematic_break_border_color,
+          line_width: @theme.thematic_break_border_width,
+          line_style: (@theme.thematic_break_border_style&.to_sym || :solid)
         theme_margin :thematic_break, ((block_next = next_enclosed_block node) ? :bottom : :top), block_next || true
       end
 
       def convert_toc node, opts = {}
-        # NOTE: only allow document to have a single toc
+        # NOTE: only allow document to have a single managed toc
         return if @toc_extent
         is_macro = (placement = opts[:placement] || 'macro') == 'macro'
         if ((doc = node.document).attr? 'toc-placement', placement) && (doc.attr? 'toc') && doc.sections?
@@ -2356,11 +2370,11 @@ module Asciidoctor
             start_new_page if @ppbook && verso_page? && !(is_macro && (node.option? 'nonfacing'))
           end
           add_dest_for_block node, id: (node.id || 'toc') if is_macro
-          allocate_toc doc, (doc.attr 'toclevels', 2).to_i, cursor, (use_title_page = is_book || (doc.attr? 'title-page'))
-          @index.start_page_number = @toc_extent.to.page + 1 if use_title_page && @theme.page_numbering_start_at == 'after-toc'
+          toc_extent = @toc_extent = allocate_toc doc, (doc.attr 'toclevels', 2).to_i, cursor, (title_page_on = is_book || (doc.attr? 'title-page'))
+          @index.start_page_number = toc_extent.to.page + 1 if title_page_on && @theme.page_numbering_start_at == 'after-toc'
           if is_macro
-            @disable_running_content[:header] += @toc_extent.page_range if node.option? 'noheader'
-            @disable_running_content[:footer] += @toc_extent.page_range if node.option? 'nofooter'
+            @disable_running_content[:header] += toc_extent.page_range if node.option? 'noheader'
+            @disable_running_content[:footer] += toc_extent.page_range if node.option? 'nofooter'
           end
         end
         nil
@@ -2378,7 +2392,7 @@ module Asciidoctor
 
         if at_page_top?
           if page_layout && page_layout != page.layout && page.empty?
-            delete_page
+            delete_current_page
             advance_page layout: page_layout
           end
         elsif page_layout
@@ -2388,8 +2402,9 @@ module Asciidoctor
         end
       end
 
-      def convert_index_section _node
+      def convert_index_section node
         space_needed_for_category = @theme.description_list_term_spacing + (2 * (height_of_typeset_text 'A'))
+        pagenum_sequence_style = node.document.attr 'index-pagenum-sequence-style'
         column_box [0, cursor], columns: @theme.index_columns, width: bounds.width, reflow_margins: true do
           def @bounding_box.move_past_bottom *args # rubocop:disable Lint/NestedMethodDefinition
             super(*args)
@@ -2398,12 +2413,12 @@ module Asciidoctor
           @index.categories.each do |category|
             # NOTE: cursor method always returns 0 inside column_box; breaks reference_bounds.move_past_bottom
             bounds.move_past_bottom if space_needed_for_category > y - reference_bounds.absolute_bottom
-            layout_prose category.name,
+            ink_prose category.name,
               align: :left,
               inline_format: false,
               margin_bottom: @theme.description_list_term_spacing,
-              style: @theme.description_list_term_font_style.to_sym
-            category.terms.each {|term| convert_index_list_item term }
+              style: @theme.description_list_term_font_style&.to_sym
+            category.terms.each {|term| convert_index_list_item term, pagenum_sequence_style }
             # NOTE: see previous note for why we can't use margin_bottom method
             if @theme.prose_margin_bottom > y - reference_bounds.absolute_bottom
               bounds.move_past_bottom
@@ -2415,21 +2430,32 @@ module Asciidoctor
         nil
       end
 
-      def convert_index_list_item term
+      def convert_index_list_item term, pagenum_sequence_style = nil
         text = escape_xml term.name
         unless term.container?
           if @media == 'screen'
-            pagenums = term.dests.map {|dest| %(<a anchor="#{dest[:anchor]}">#{dest[:page]}</a>) }
+            case pagenum_sequence_style
+            when 'page'
+              pagenums = term.dests.uniq {|dest| dest[:page] }.map {|dest| %(<a anchor="#{dest[:anchor]}">#{dest[:page]}</a>) }
+            when 'range'
+              first_anchor_per_page = term.dests.each_with_object({}) {|dest, accum| accum[dest[:page]] ||= dest[:anchor] }
+              pagenums = (consolidate_ranges first_anchor_per_page.keys).map do |range|
+                anchor = first_anchor_per_page[(range.include? '-') ? (range.partition '-')[0] : range]
+                %(<a anchor="#{anchor}">#{range}</a>)
+              end
+            else # term
+              pagenums = term.dests.map {|dest| %(<a anchor="#{dest[:anchor]}">#{dest[:page]}</a>) }
+            end
           else
-            pagenums = consolidate_ranges term.dests.uniq {|dest| dest[:page] }.map {|dest| dest[:page] } # rubocop:disable Lint/AmbiguousBlockAssociation
+            pagenums = consolidate_ranges term.dests.map {|dest| dest[:page] }.uniq
           end
           text = %(#{text}, #{pagenums.join ', '})
         end
         subterm_indent = @theme.description_list_description_indent
-        layout_prose text, align: :left, margin: 0, hanging_indent: subterm_indent * 2
+        ink_prose text, align: :left, margin: 0, hanging_indent: subterm_indent * 2
         indent subterm_indent do
           term.subterms.each do |subterm|
-            convert_index_list_item subterm
+            convert_index_list_item subterm, pagenum_sequence_style
           end
         end unless term.leaf?
       end
@@ -2527,14 +2553,14 @@ module Asciidoctor
       end
 
       def convert_inline_icon node
-        if node.document.attr? 'icons', 'font'
+        if (icons = (doc = node.document).attr 'icons') == 'font'
           if (icon_name = node.target).include? '@'
             icon_name, icon_set = icon_name.split '@', 2
             explicit_icon_set = true
           elsif (icon_set = node.attr 'set')
             explicit_icon_set = true
           else
-            icon_set = node.document.attr 'icon-set', 'fa'
+            icon_set = doc.attr 'icon-set', 'fa'
           end
           if icon_set == 'fa' || !(IconSets.include? icon_set)
             icon_set = 'fa'
@@ -2580,6 +2606,14 @@ module Asciidoctor
             log :warn, %(#{icon_name} is not a valid icon name in the #{icon_set} icon set)
             %([#{node.attr 'alt'}&#93;)
           end
+        elsif icons
+          image_path = ::File.absolute_path %(#{icon_name = node.target}.#{image_format = doc.attr 'icontype', 'png'}), (doc.attr 'iconsdir')
+          if ::File.readable? image_path
+            %(<img src="#{image_path}" format="#{image_format}" alt="#{node.attr 'alt'}" fit="line">)
+          else
+            log :warn, %(image icon for '#{icon_name}' not found or not readable: #{image_path})
+            %([#{icon_name}&#93;)
+          end
         else
           %([#{node.attr 'alt'}&#93;)
         end
@@ -2616,15 +2650,16 @@ module Asciidoctor
       end
 
       def convert_inline_indexterm node
+        visible = node.type == :visible
         if scratch?
-          node.type == :visible ? node.text : ''
+          visible ? node.text : ''
         else
           # NOTE: initialize index in case converter is called before PDF is initialized
           @index ||= IndexCatalog.new
           # NOTE: page number (:page key) is added by InlineDestinationMarker
           dest = { anchor: (anchor_name = @index.next_anchor_name) }
-          anchor = %(<a id="#{anchor_name}" type="indexterm">#{DummyText}</a>)
-          if node.type == :visible
+          anchor = %(<a id="#{anchor_name}" type="indexterm"#{visible ? ' visible="true"' : ''}>#{DummyText}</a>)
+          if visible
             visible_term = node.text
             @index.store_primary_term (sanitize visible_term), dest
             %(#{anchor}#{visible_term})
@@ -2671,8 +2706,10 @@ module Asciidoctor
           open, close, is_tag = ['<sub>', '</sub>', true]
         when :double
           open, close, is_tag = [theme.quotes[0], theme.quotes[1], false]
+          quotes = true
         when :single
           open, close, is_tag = [theme.quotes[2], theme.quotes[3], false]
+          quotes = true
         when :mark
           open, close, is_tag = ['<mark>', '</mark>', true]
         else
@@ -2681,6 +2718,11 @@ module Asciidoctor
 
         inner_text = node.text
 
+        if quotes && (len = inner_text.length) > 3 &&
+            (inner_text.end_with? '...') && !((inner_text_trunc = inner_text.slice 0, len - 3).end_with? ?\\)
+          inner_text = inner_text_trunc + '&#8230;'
+        end
+
         if (roles = node.role)
           roles.split.each do |role|
             if (text_transform = theme[%(role_#{role}_text_transform)])
@@ -2697,7 +2739,8 @@ module Asciidoctor
         node.id ? %(<a id="#{node.id}">#{DummyText}</a>#{quoted_text}) : quoted_text
       end
 
-      def layout_title_page doc
+      # Returns a Boolean indicating whether the title page was created
+      def ink_title_page doc
         return unless doc.header? && !doc.notitle && @theme.title_page != false
 
         # NOTE: a new page may have already been started at this point, so decide what to do with it
@@ -2724,7 +2767,7 @@ module Asciidoctor
         font @theme.base_font_family, size: @root_font_size, style: @theme.base_font_style
 
         # QUESTION: allow alignment per element on title page?
-        title_align = (@theme.title_page_align || @base_align).to_sym
+        title_align = (@theme.title_page_text_align || @base_text_align).to_sym
 
         if @theme.title_page_logo_display != 'none' && (logo_image_path = (doc.attr 'title-logo-image') || (logo_image_from_theme = @theme.title_page_logo_image))
           if (logo_image_path.include? ':') && logo_image_path =~ ImageAttributeValueRx
@@ -2773,7 +2816,7 @@ module Asciidoctor
             move_down @theme.title_page_title_margin_top || 0
             indent (@theme.title_page_title_margin_left || 0), (@theme.title_page_title_margin_right || 0) do
               theme_font :title_page_title do
-                layout_prose doctitle.main, align: title_align, margin: 0
+                ink_prose doctitle.main, align: title_align, margin: 0
               end
             end
             move_down @theme.title_page_title_margin_bottom || 0
@@ -2782,7 +2825,7 @@ module Asciidoctor
             move_down @theme.title_page_subtitle_margin_top || 0
             indent (@theme.title_page_subtitle_margin_left || 0), (@theme.title_page_subtitle_margin_right || 0) do
               theme_font :title_page_subtitle do
-                layout_prose subtitle, align: title_align, margin: 0
+                ink_prose subtitle, align: title_align, margin: 0
               end
             end
             move_down @theme.title_page_subtitle_margin_bottom || 0
@@ -2807,7 +2850,7 @@ module Asciidoctor
                 end
               end.join @theme.title_page_authors_delimiter
               theme_font :title_page_authors do
-                layout_prose authors, align: title_align, margin: 0, normalize: true
+                ink_prose authors, align: title_align, margin: 0, normalize: true
               end
             end
             move_down @theme.title_page_authors_margin_bottom || 0
@@ -2820,17 +2863,18 @@ module Asciidoctor
             end
             indent (@theme.title_page_revision_margin_left || 0), (@theme.title_page_revision_margin_right || 0) do
               theme_font :title_page_revision do
-                layout_prose revision_text, align: title_align, margin: 0, normalize: false
+                ink_prose revision_text, align: title_align, margin: 0, normalize: false
               end
             end
             move_down @theme.title_page_revision_margin_bottom || 0
           end
         end
 
-        layout_prose DummyText, margin: 0, line_height: 1, normalize: false if page.empty?
+        ink_prose DummyText, margin: 0, line_height: 1, normalize: false if page.empty?
+        true
       end
 
-      def layout_cover_page doc, face
+      def ink_cover_page doc, face
         image_path, image_opts = resolve_background_image doc, @theme, %(#{face}-cover-image), theme_key: %(cover_#{face}_image).to_sym, symbolic_paths: ['', '~']
         if image_path
           if image_path.empty?
@@ -2876,71 +2920,109 @@ module Asciidoctor
 
       def start_new_chapter chapter
         start_new_page unless at_page_top?
-        # TODO: must call update_colors before advancing to next page if start_new_page is called in layout_chapter_title
+        # TODO: must call update_colors before advancing to next page if start_new_page is called in ink_chapter_title
         start_new_page if @ppbook && verso_page? && !(chapter.option? 'nonfacing')
       end
 
       alias start_new_part start_new_chapter
 
       def arrange_section sect, title, opts
-        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]
+                ink_part_title sect, title, opts
+              elsif opts[:chapterlike]
+                ink_chapter_title sect, title, opts
+              else
+                ink_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
+            h_padding_t, h_padding_r, h_padding_b, h_padding_l = expand_padding_value @theme[%(heading_h#{hlevel}_padding)]
+            h_fits = indent h_padding_l, h_padding_r do
+              # FIXME: this height doesn't account for impact of text transform or inline formatting
+              heading_h = (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) + h_padding_t + h_padding_b
+              heading_h += @theme.heading_min_height_after if @theme.heading_min_height_after && sect.blocks?
+              cursor >= heading_h
+            end
+            start_new_page unless h_fits
+          end
         end
+        nil
       end
 
-      def layout_chapter_title node, title, opts = {}
-        layout_general_heading node, title, (opts.merge outdent: true)
+      def ink_chapter_title node, title, opts = {}
+        ink_general_heading node, title, (opts.merge outdent: true)
       end
 
-      alias layout_part_title layout_chapter_title
+      alias ink_part_title ink_chapter_title
 
-      def layout_general_heading _node, title, opts = {}
-        layout_heading title, opts
+      def ink_general_heading _node, title, opts = {}
+        ink_heading title, opts
       end
 
-      # NOTE: layout_heading doesn't set the theme font because it's used for various types of headings
-      def layout_heading string, opts = {}
-        hlevel = opts[:level]
+      # NOTE: ink_heading doesn't set the theme font because it's used for various types of headings
+      def ink_heading string, opts = {}
+        if (h_level = opts[:level])
+          h_category = %(heading_h#{h_level})
+        end
         unless (top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top))
           if at_page_top?
-            if hlevel && (top_margin = @theme[%(heading_h#{hlevel}_margin_page_top)] || @theme.heading_margin_page_top) > 0
+            if h_category && (top_margin = @theme[%(#{h_category}_margin_page_top)] || @theme.heading_margin_page_top) > 0
               move_down top_margin
             end
             top_margin = 0
           else
-            top_margin = (hlevel ? @theme[%(heading_h#{hlevel}_margin_top)] : nil) || @theme.heading_margin_top
+            top_margin = (h_category ? @theme[%(#{h_category}_margin_top)] : nil) || @theme.heading_margin_top
           end
         end
-        bot_margin = margin || (opts.delete :margin_bottom) || (hlevel ? @theme[%(heading_h#{hlevel}_margin_bottom)] : nil) || @theme.heading_margin_bottom
+        bot_margin = margin || (opts.delete :margin_bottom) || (h_category ? @theme[%(#{h_category}_margin_bottom)] : nil) || @theme.heading_margin_bottom
         if (transform = resolve_text_transform opts)
           string = transform_text string, transform
         end
         outdent_section opts.delete :outdent do
           margin_top top_margin
-          # QUESTION: should we move inherited styles to typeset_text?
-          if (inherited = apply_text_decoration font_styles, :heading, hlevel).empty?
-            inline_format_opts = true
-          else
-            inline_format_opts = [{ inherited: inherited }]
+          start_cursor = cursor
+          start_page_number = page_number
+          pad_box h_category ? @theme[%(#{h_category}_padding)] : nil do
+            # QUESTION: should we move inherited styles to typeset_text?
+            if (inherited = apply_text_decoration font_styles, :heading, h_level).empty?
+              inline_format_opts = true
+            else
+              inline_format_opts = [{ inherited: inherited }]
+            end
+            typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
+              color: @font_color,
+              inline_format: inline_format_opts,
+              align: @base_text_align.to_sym,
+            }.merge(opts)
+          end
+          if h_category && @theme[%(#{h_category}_border_width)] &&
+              (@theme[%(#{h_category}_border_color)] || @theme.base_border_color) && page_number == start_page_number
+            float do
+              bounding_box [bounds.left, start_cursor], width: bounds.width, height: start_cursor - cursor do
+                theme_fill_and_stroke_bounds h_category
+              end
+            end
           end
-          typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
-            color: @font_color,
-            inline_format: inline_format_opts,
-            align: @base_align.to_sym,
-          }.merge(opts)
           margin_bottom bot_margin
         end
       end
 
       # NOTE: inline_format is true by default
-      def layout_prose string, opts = {}
+      def ink_prose string, opts = {}
         top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || 0
         bot_margin = margin || (opts.delete :margin_bottom) || @theme.prose_margin_bottom
         if (transform = resolve_text_transform opts)
@@ -2964,7 +3046,7 @@ module Asciidoctor
         typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
           color: @font_color,
           inline_format: [inline_format_opts],
-          align: @base_align.to_sym,
+          align: @base_text_align.to_sym,
         }.merge(opts)
         margin_bottom bot_margin
       end
@@ -2987,13 +3069,13 @@ module Asciidoctor
       # The subject argument can either be a String or an AbstractNode. If
       # subject is an AbstractNode, only call this method if the node has a
       # title (i.e., subject.title? returns true).
-      def layout_caption subject, opts = {}
+      def ink_caption subject, opts = {}
         if opts.delete :dry_run
           force_top_margin = !at_page_top? if (force_top_margin = opts.delete :force_top_margin).nil?
           return (dry_run keep_together: true, single_page: :enforce do
             # TODO: encapsulate this logic to force top margin to be applied
             margin_box.instance_variable_set :@y, margin_box.absolute_top + 0.0001 if force_top_margin
-            layout_caption subject, opts
+            ink_caption subject, opts
           end).single_page_height
         end
         if ::Asciidoctor::AbstractBlock === subject
@@ -3001,21 +3083,23 @@ module Asciidoctor
         else
           string = subject.to_s
         end
+        block_align = opts.delete :block_align
+        block_width = opts.delete :block_width
         category_caption = (category = opts[:category]) ? %(#{category}_caption) : 'caption'
+        caption_margin_outside = @theme[%(#{category_caption}_margin_outside)] || @theme.caption_margin_outside
+        caption_margin_inside = @theme[%(#{category_caption}_margin_inside)] || @theme.caption_margin_inside
         container_width = bounds.width
-        block_align = opts.delete :block_align
+        indent_by = [0, 0]
         if (align = @theme[%(#{category_caption}_align)] || @theme.caption_align)
-          align = align == 'inherit' ? (block_align || @base_align.to_sym) : align.to_sym
+          align = align == 'inherit' ? (block_align || @base_text_align.to_sym) : align.to_sym
         else
-          align = @base_align.to_sym
+          align = @base_text_align.to_sym
         end
         if (text_align = @theme[%(#{category_caption}_text_align)] || @theme.caption_text_align)
           text_align = text_align == 'inherit' ? align : text_align.to_sym
         else
           text_align = align
         end
-        indent_by = [0, 0]
-        block_width = opts.delete :block_width
         if (max_width = opts.delete :max_width) && max_width != 'none'
           if ::String === max_width
             if max_width.start_with? 'fit-content'
@@ -3047,9 +3131,7 @@ module Asciidoctor
           end
         end
         theme_font_cascade [:caption, category_caption] do
-          caption_margin_outside = @theme[%(#{category_caption}_margin_outside)] || @theme.caption_margin_outside
-          caption_margin_inside = @theme[%(#{category_caption}_margin_inside)] || @theme.caption_margin_inside
-          if ((opts.delete :side) || :top) == :top
+          if ((opts.delete :end) || (opts.delete :side) || :top) == :top
             margin = { top: caption_margin_outside, bottom: caption_margin_inside }
           else
             margin = { top: caption_margin_inside, bottom: caption_margin_outside }
@@ -3057,8 +3139,13 @@ module Asciidoctor
           unless (inherited = apply_text_decoration [], :caption).empty?
             opts = opts.merge inherited
           end
+          unless scratch? || !(bg_color = @theme[%(#{category_caption}_background_color)] || @theme.caption_background_color)
+            caption_height = height_of_typeset_text string
+            fill_at = [0, cursor + (margin[:top] || 0)]
+            float { bounding_box(fill_at, width: container_width, height: caption_height) { fill_bounds bg_color } }
+          end
           indent(*indent_by) do
-            layout_prose string, ({
+            ink_prose string, ({
               margin_top: margin[:top],
               margin_bottom: margin[:bottom],
               align: text_align,
@@ -3072,35 +3159,45 @@ module Asciidoctor
       end
 
       # Render the caption for a table and return the height of the rendered content
-      def layout_table_caption node, table_alignment = :left, table_width = nil, max_width = nil, side = :top
-        layout_caption node, category: :table, side: side, block_align: table_alignment, block_width: table_width, max_width: max_width
+      def ink_table_caption node, table_alignment = :left, table_width = nil, max_width = nil, end_ = :top
+        ink_caption node, category: :table, end: end_, block_align: table_alignment, block_width: table_width, max_width: max_width
       end
 
-      def allocate_toc doc, toc_num_levels, toc_start_cursor, use_title_page
-        toc_start_page = page_number
+      def allocate_toc doc, toc_num_levels, toc_start_cursor, title_page_on
+        toc_start_page_number = page_number
+        to_page = nil
         extent = dry_run onto: self do
-          layout_toc doc, toc_num_levels, toc_start_page, toc_start_cursor
-          margin_bottom @theme.block_margin_bottom unless use_title_page
+          to_page = (ink_toc doc, toc_num_levels, toc_start_page_number, toc_start_cursor).end
+          margin_bottom @theme.block_margin_bottom unless title_page_on
+        end
+        # NOTE: patch for custom converters that allocate extra TOC pages without actually creating them
+        if to_page > extent.to.page
+          extent.to.page = to_page
+          extent.to.cursor = bounds.height
         end
         # NOTE: reserve pages for the toc; leaves cursor on page after last page in toc
-        if use_title_page
+        if title_page_on
           extent.each_page { start_new_page }
         else
           extent.each_page {|first_page| start_new_page unless first_page }
           move_cursor_to extent.to.cursor
         end
-        @toc_extent = extent
+        extent
+      end
+
+      def get_entries_for_toc node
+        node.sections
       end
 
       # NOTE: num_front_matter_pages not used during a dry run
-      def layout_toc doc, num_levels, toc_page_number, start_cursor, num_front_matter_pages = 0
+      def ink_toc doc, num_levels, toc_page_number, start_cursor, num_front_matter_pages = 0
         go_to_page toc_page_number unless (page_number == toc_page_number) || scratch?
         start_page_number = page_number
         move_cursor_to start_cursor
         unless (toc_title = doc.attr 'toc-title').nil_or_empty?
           theme_font_cascade [[:heading, level: 2], :toc_title] do
-            toc_title_align = (@theme.toc_title_align || @theme.heading_h2_align || @theme.heading_align || @base_align).to_sym
-            layout_general_heading doc, toc_title, align: toc_title_align, level: 2, outdent: true, role: :toctitle
+            toc_title_align = (@theme.toc_title_text_align || @theme.heading_h2_text_align || @theme.heading_text_align || @base_text_align).to_sym
+            ink_general_heading doc, toc_title, align: toc_title_align, level: 2, outdent: true, role: :toctitle
           end
         end
         # QUESTION: should we skip this whole method if num_levels < 0?
@@ -3125,7 +3222,7 @@ module Asciidoctor
             }
           end
           theme_margin :toc, :top
-          layout_toc_level doc.sections, num_levels, dot_leader, num_front_matter_pages
+          ink_toc_level (get_entries_for_toc doc), num_levels, dot_leader, num_front_matter_pages
         end
         # NOTE: range must be calculated relative to toc_page_number; absolute page number in scratch document is arbitrary
         toc_page_numbers = (toc_page_number..(toc_page_number + (page_number - start_page_number)))
@@ -3133,38 +3230,48 @@ module Asciidoctor
         toc_page_numbers
       end
 
-      def layout_toc_level sections, num_levels, dot_leader, num_front_matter_pages
+      def ink_toc_level entries, num_levels, dot_leader, num_front_matter_pages
         # NOTE: font options aren't always reliable, so store size separately
         toc_font_info = theme_font :toc do
           { font: font, size: @font_size }
         end
         hanging_indent = @theme.toc_hanging_indent
-        sections.each do |sect|
-          next if (num_levels_for_sect = (sect.attr 'toclevels', num_levels).to_i) < sect.level
-          theme_font :toc, level: (sect.level + 1) do
-            sect_title = @text_transform ? (transform_text sect.numbered_title, @text_transform) : sect.numbered_title
-            next if sect_title.empty?
+        entries.each do |entry|
+          next if (num_levels_for_entry = (entry.attr 'toclevels', num_levels).to_i) < (entry_level = entry.level + 1).pred
+          theme_font :toc, level: entry_level do
+            next unless (entry_anchor = (entry.attr 'pdf-anchor') || entry.id)
+            entry_title = entry.context == :section ? entry.numbered_title : (entry.title? ? entry.title : (entry.xreftext 'basic'))
+            next if entry_title.empty?
+            entry_title = transform_text entry_title, @text_transform if @text_transform
             pgnum_label_placeholder_width = rendered_width_of_string '0' * @toc_max_pagenum_digits
-            # NOTE: only write section title (excluding dots and page number) if this is a dry run
+            # NOTE: only write title (excluding dots and page number) if this is a dry run
             if scratch?
               indent 0, pgnum_label_placeholder_width do
                 # NOTE: must wrap title in empty anchor element in case links are styled with different font family / size
-                layout_prose sect_title, anchor: true, normalize: false, hanging_indent: hanging_indent, normalize_line_height: true, margin: 0
+                ink_prose entry_title, anchor: true, normalize: false, hanging_indent: hanging_indent, normalize_line_height: true, margin: 0
               end
             else
-              physical_pgnum = sect.attr 'pdf-page-start'
-              virtual_pgnum = physical_pgnum - num_front_matter_pages
-              pgnum_label = (virtual_pgnum < 1 ? (RomanNumeral.new physical_pgnum, :lower) : virtual_pgnum).to_s
+              if !(physical_pgnum = entry.attr 'pdf-page-start') &&
+                  (target_page_ref = (get_dest entry_anchor)&.first) &&
+                  (target_page_idx = state.pages.index {|candidate| candidate.dictionary == target_page_ref })
+                physical_pgnum = target_page_idx + 1
+              end
+              if physical_pgnum
+                virtual_pgnum = physical_pgnum - num_front_matter_pages
+                pgnum_label = (virtual_pgnum < 1 ? (RomanNumeral.new physical_pgnum, :lower) : virtual_pgnum).to_s
+              else
+                pgnum_label = '?'
+              end
               start_page_number = page_number
               start_cursor = cursor
               start_dots = nil
-              sect_title_inherited = (apply_text_decoration ::Set.new, :toc, sect.level.next).merge anchor: (sect_anchor = sect.attr 'pdf-anchor'), color: @font_color
+              entry_title_inherited = (apply_text_decoration ::Set.new, :toc, entry_level).merge anchor: entry_anchor, color: @font_color
               # NOTE: use text formatter to add anchor overlay to avoid using inline format with synthetic anchor tag
-              sect_title_fragments = text_formatter.format sect_title, inherited: sect_title_inherited
+              entry_title_fragments = text_formatter.format entry_title, inherited: entry_title_inherited
               line_metrics = calc_line_metrics @base_line_height
               indent 0, pgnum_label_placeholder_width do
-                (sect_title_fragments[-1][:callback] ||= []) << (last_fragment_pos = ::Asciidoctor::PDF::FormattedText::FragmentPositionRenderer.new)
-                typeset_formatted_text sect_title_fragments, line_metrics, hanging_indent: hanging_indent, normalize_line_height: true
+                (entry_title_fragments[-1][:callback] ||= []) << (last_fragment_pos = ::Asciidoctor::PDF::FormattedText::FragmentPositionRenderer.new)
+                typeset_formatted_text entry_title_fragments, line_metrics, hanging_indent: hanging_indent, normalize_line_height: true
                 start_dots = last_fragment_pos.right + hanging_indent
                 last_fragment_cursor = last_fragment_pos.top + line_metrics.padding_top
                 start_cursor = last_fragment_cursor if last_fragment_pos.page_number > start_page_number || (start_cursor - last_fragment_cursor) > line_metrics.height
@@ -3172,7 +3279,7 @@ module Asciidoctor
               end_cursor = cursor
               move_cursor_to start_cursor
               # NOTE: we're guaranteed to be on the same page as the final line of the entry
-              if dot_leader[:width] > 0 && (dot_leader[:levels].include? sect.level)
+              if dot_leader[:width] > 0 && (dot_leader[:levels].include? entry_level.pred)
                 pgnum_label_width = rendered_width_of_string pgnum_label
                 pgnum_label_font_settings = { color: @font_color, font: font_family, size: @font_size, styles: font_styles }
                 save_font do
@@ -3184,18 +3291,18 @@ module Asciidoctor
                   typeset_formatted_text [
                     { text: dot_leader[:text] * num_dots, color: dot_leader[:font_color] },
                     dot_leader[:spacer],
-                    ({ text: pgnum_label, anchor: sect_anchor }.merge pgnum_label_font_settings),
+                    ({ text: pgnum_label, anchor: entry_anchor }.merge pgnum_label_font_settings),
                   ], line_metrics, align: :right
                 end
               else
-                typeset_formatted_text [{ text: pgnum_label, color: @font_color, anchor: sect_anchor }], line_metrics, align: :right
+                typeset_formatted_text [{ text: pgnum_label, color: @font_color, anchor: entry_anchor }], line_metrics, align: :right
               end
               move_cursor_to end_cursor
             end
           end
           indent @theme.toc_indent do
-            layout_toc_level sect.sections, num_levels_for_sect, dot_leader, num_front_matter_pages
-          end if num_levels_for_sect > sect.level
+            ink_toc_level (get_entries_for_toc entry), num_levels_for_entry, dot_leader, num_front_matter_pages
+          end if num_levels_for_entry >= entry_level
         end
       end
 
@@ -3222,15 +3329,15 @@ module Asciidoctor
         icon_data
       end
 
-      # TODO: delegate to layout_page_header and layout_page_footer per page
-      def layout_running_content periphery, doc, skip = [1, 1], body_start_page_number = 1
+      # TODO: delegate to ink_page_header and ink_page_footer per page
+      def ink_running_content periphery, doc, skip = [1, 1], body_start_page_number = 1
         skip_pages, skip_pagenums = skip
         # NOTE: find and advance to first non-imported content page to use as model page
-        return unless (content_start_page = state.pages[skip_pages..-1].index {|it| !it.imported_page? })
-        content_start_page += (skip_pages + 1)
+        return unless (content_start_page_number = state.pages[skip_pages..-1].index {|it| !it.imported_page? })
+        content_start_page_number += (skip_pages + 1)
         num_pages = page_count
         prev_page_number = page_number
-        go_to_page content_start_page
+        go_to_page content_start_page_number
 
         # FIXME: probably need to treat doctypes differently
         is_book = doc.doctype == 'book'
@@ -3326,7 +3433,7 @@ module Asciidoctor
         pagenums_enabled = doc.attr? 'pagenums'
         periphery_layout_cache = {}
         # NOTE: this block is invoked during PDF generation, after #write -> #render_file and thus after #convert_document
-        repeat (content_start_page..num_pages), dynamic: true do
+        repeat (content_start_page_number..num_pages), dynamic: true do
           pgnum = page_number
           # NOTE: don't write on pages which are imported / inserts (otherwise we can get a corrupt PDF)
           next if page.imported_page? || (disable_on_pages.include? pgnum)
@@ -3363,7 +3470,7 @@ module Asciidoctor
           theme_font periphery do
             canvas do
               bounding_box [trim_styles[:content_left][side], trim_styles[:top][side]], width: trim_styles[:content_width][side], height: trim_styles[:height] do
-                if (trim_column_rule_width = trim_styles[:column_rule_width]) > 0
+                if trim_styles[:column_rule_color] && (trim_column_rule_width = trim_styles[:column_rule_width]) > 0
                   trim_column_rule_spacing = trim_styles[:column_rule_spacing]
                 else
                   trim_column_rule_width = nil
@@ -3448,7 +3555,7 @@ module Asciidoctor
           trim_content_margin_recto = @theme[%(#{periphery}_recto_content_margin)] || @theme[%(#{periphery}_content_margin)] || [0, 'inherit', 0, 'inherit']
           trim_content_margin_recto = (expand_margin_value trim_content_margin_recto).map.with_index {|v, i| i.odd? && v == 'inherit' ? page_margin_recto[i] - trim_margin_recto[i] : v.to_f }
           if (trim_padding_recto = @theme[%(#{periphery}_recto_padding)] || @theme[%(#{periphery}_padding)])
-            trim_padding_recto = (expand_margin_value trim_padding_recto).map.with_index {|v, i| v + trim_content_margin_recto[i] }
+            trim_padding_recto = (expand_padding_value trim_padding_recto).map.with_index {|v, i| v + trim_content_margin_recto[i] }
           else
             trim_padding_recto = trim_content_margin_recto
           end
@@ -3458,7 +3565,7 @@ module Asciidoctor
           trim_content_margin_verso = @theme[%(#{periphery}_verso_content_margin)] || @theme[%(#{periphery}_content_margin)] || [0, 'inherit', 0, 'inherit']
           trim_content_margin_verso = (expand_margin_value trim_content_margin_verso).map.with_index {|v, i| i.odd? && v == 'inherit' ? page_margin_verso[i] - trim_margin_verso[i] : v.to_f }
           if (trim_padding_verso = @theme[%(#{periphery}_verso_padding)] || @theme[%(#{periphery}_padding)])
-            trim_padding_verso = (expand_margin_value trim_padding_verso).map.with_index {|v, i| v + trim_content_margin_verso[i] }
+            trim_padding_verso = (expand_padding_value trim_padding_verso).map.with_index {|v, i| v + trim_content_margin_verso[i] }
           else
             trim_padding_verso = trim_content_margin_verso
           end
@@ -3471,12 +3578,12 @@ module Asciidoctor
             # NOTE: we've already verified this property is set
             height: (trim_height = @theme[%(#{periphery}_height)]),
             bg_color: (resolve_theme_color %(#{periphery}_background_color).to_sym),
-            border_color: (trim_border_color = resolve_theme_color %(#{periphery}_border_color).to_sym),
+            border_width: (trim_border_width = @theme[%(#{periphery}_border_width)] || 0),
+            border_color: trim_border_width > 0 ? (resolve_theme_color %(#{periphery}_border_color).to_sym, @theme.base_border_color) : nil,
             border_style: (@theme[%(#{periphery}_border_style)]&.to_sym || :solid),
-            border_width: (trim_border_width = trim_border_color ? @theme[%(#{periphery}_border_width)] || @theme.base_border_width : 0),
-            column_rule_color: (trim_column_rule_color = resolve_theme_color %(#{periphery}_column_rule_color).to_sym),
+            column_rule_width: (trim_column_rule_width = @theme[%(#{periphery}_column_rule_width)] || 0),
+            column_rule_color: trim_column_rule_width > 0 ? (resolve_theme_color %(#{periphery}_column_rule_color).to_sym) : nil,
             column_rule_style: (@theme[%(#{periphery}_column_rule_style)]&.to_sym || :solid),
-            column_rule_width: (trim_column_rule_color ? @theme[%(#{periphery}_column_rule_width)] || 0 : 0),
             column_rule_spacing: (@theme[%(#{periphery}_column_rule_spacing)] || 0),
             valign: valign_offset ? [valign, valign_offset] : valign,
             img_valign: @theme[%(#{periphery}_image_vertical_align)],
@@ -3644,8 +3751,9 @@ module Asciidoctor
         outline.define do
           initial_pagenum = has_front_cover ? 2 : 1
           # FIXME: use sanitize: :plain_text on Document#doctitle once available
-          if document.page_count >= initial_pagenum && (doctitle = document.resolve_doctitle doc)
-            page title: (document.sanitize doctitle), destination: (document.dest_top initial_pagenum)
+          if document.page_count >= initial_pagenum && (outline_title = doc.attr 'outline-title') &&
+              (outline_title.empty? ? (outline_title = document.resolve_doctitle doc) : outline_title)
+            page title: (document.sanitize outline_title), destination: (document.dest_top initial_pagenum)
           end
           # QUESTION: is there any way to get add_outline_level to invoke in the context of the outline?
           document.add_outline_level self, doc.sections, num_levels, expand_levels
@@ -3707,7 +3815,14 @@ module Asciidoctor
           pdf_doc.render_file target
           # QUESTION: restore attributes first?
           @pdfmark&.generate_file target
-          (Optimizer.new @optimize, pdf_doc.min_version).optimize_file target if @optimize
+          if (quality = @optimize)
+            if quality.include? ','
+              quality, compliance = quality.split ',', 2
+            elsif quality.include? '/'
+              quality, compliance = nil, quality
+            end
+            (Optimizer.new quality, pdf_doc.min_version, compliance).optimize_file target
+          end
           to_file = true
         end
         if !ENV['KEEP_ARTIFACTS']
@@ -3759,7 +3874,7 @@ module Asciidoctor
       end
 
       def resolve_text_transform key, use_fallback = true
-        if (transform = ::Hash === key ? (key.delete :text_transform) : @theme[key.to_s])
+        if (transform = ::Hash === key ? (key.delete :text_transform) : @theme[key])
           transform == 'none' ? nil : transform
         elsif use_fallback
           @text_transform
@@ -3768,9 +3883,9 @@ module Asciidoctor
 
       # QUESTION: should we pass a category as an argument?
       # QUESTION: should we make this a method on the theme ostruct? (e.g., @theme.resolve_color key, fallback)
-      def resolve_theme_color key, fallback_color = nil
-        if (color = @theme[key.to_s]) && color != 'transparent'
-          color
+      def resolve_theme_color key, fallback_color = nil, transparent_color = fallback_color
+        if (color = @theme[key])
+          color == 'transparent' ? transparent_color : color
         else
           fallback_color
         end
@@ -3781,7 +3896,7 @@ module Asciidoctor
       end
 
       def theme_fill_and_stroke_bounds category, opts = {}
-        fill_and_stroke_bounds opts[:background_color], @theme[%(#{category}_border_color)],
+        fill_and_stroke_bounds opts[:background_color], @theme[%(#{category}_border_color)] || @theme.base_border_color,
           line_width: @theme[%(#{category}_border_width)],
           line_style: (@theme[%(#{category}_border_style)]&.to_sym || :solid),
           radius: @theme[%(#{category}_border_radius)]
@@ -3790,7 +3905,7 @@ module Asciidoctor
       def theme_fill_and_stroke_block category, extent, opts = {}
         node_with_caption = nil unless (node_with_caption = opts[:caption_node])&.title?
         unless extent
-          layout_caption node_with_caption, category: category if node_with_caption
+          ink_caption node_with_caption, category: category if node_with_caption
           return
         end
         if (b_width = (opts.key? :border_width) ? opts[:border_width] : @theme[%(#{category}_border_width)])
@@ -3804,14 +3919,12 @@ module Asciidoctor
           bg_color = nil
         end
         unless b_width || bg_color
-          layout_caption node_with_caption, category: category if node_with_caption
+          ink_caption node_with_caption, category: category if node_with_caption
           return
         end
-        if (b_color = @theme[%(#{category}_border_color)]) == 'transparent'
-          b_color = @page_bg_color
-        end
+        b_color = resolve_theme_color %(#{category}_border_color).to_sym, @theme.base_border_color, @page_bg_color
         b_radius ||= (@theme[%(#{category}_border_radius)] || 0) + (b_width || 0)
-        if b_width && b_color
+        if b_width
           if b_color == @page_bg_color # let page background cut into block background
             b_gap_color, b_shift = @page_bg_color, (b_width * 0.5)
           elsif (b_gap_color = bg_color) && b_gap_color != b_color
@@ -3822,7 +3935,7 @@ module Asciidoctor
         else # let page background cut into block background; guarantees b_width is set
           b_shift, b_gap_color = (b_width ||= 0.5) * 0.5, @page_bg_color
         end
-        layout_caption node_with_caption, category: category if node_with_caption
+        ink_caption node_with_caption, category: category if node_with_caption
         extent.from.page += 1 unless extent.from.page == page_number # sanity check
         float do
           extent.each_page do |first_page, last_page|
@@ -3959,9 +4072,7 @@ module Asciidoctor
         # NOTE: it also removes zero-width spaces
         arranger.finalize_line
         actual_width = width_of_fragments arranger.fragments
-        unless ::Array === (padding = @theme[%(#{category}_padding)])
-          padding = ::Array.new 4, padding
-        end
+        padding = expand_padding_value @theme[%(#{category}_padding)]
         if actual_width > (available_width = bounds.width - padding[3].to_f - padding[1].to_f)
           adjusted_font_size = ((available_width * font_size).to_f / actual_width).truncate 4
           if (min = @theme[%(#{category}_font_size_min)] || @theme.base_font_size_min) && adjusted_font_size < min
@@ -4206,7 +4317,7 @@ module Asciidoctor
           (align_role.slice 5, align_role.length).to_sym
         elsif use_theme
           roles.reverse.each do |role|
-            if (align = @theme[%(role_#{role}_align)])
+            if (align = @theme[%(role_#{role}_text_align)])
               return align.to_sym
             end
           end
@@ -4542,6 +4653,35 @@ module Asciidoctor
         end
       end
 
+      # Deprecated method names
+      alias layout_footnotes ink_footnotes
+      alias layout_title_page ink_title_page
+      alias layout_cover_page ink_cover_page
+      alias layout_chapter_title ink_chapter_title
+      alias layout_part_title ink_part_title
+      alias layout_general_heading ink_general_heading
+      alias layout_heading ink_heading
+      alias layout_prose ink_prose
+      alias layout_caption ink_caption
+      alias layout_table_caption ink_table_caption
+      alias layout_toc ink_toc
+      alias layout_toc_level ink_toc_level
+      alias layout_running_content ink_running_content
+
+      # intercepts "class CustomPDFConverter < (Asciidoctor::Converter.for 'pdf')"
+      def self.method_added method
+        if (method_name = method.to_s).start_with? 'layout_'
+          alias_method %(ink_#{method_name.slice 7, method_name.length}).to_sym, method
+        end
+      end
+
+      # intercepts "(Asciidoctor::Converter.for 'pdf').prepend CustomConverterExtensions"
+      def self.prepend *mods
+        super
+        mods.each {|mod| (mod.instance_methods false).each {|method| method_added method } }
+        self
+      end
+
       private
 
       def add_link_to_image uri, image_info, image_opts