asciidoctor-pdf 2.0.0.beta.2 → 2.0.0.rc.1

data/lib/asciidoctor/pdf/converter.rb

@@ -156,30 +156,6 @@ module Asciidoctor
         ::Asciidoctor::Inline === node ? result : self
       end
 
-      def traverse node, opts = {}
-        # NOTE: need to reconfigure document to use scratch converter in scratch document
-        if self == (prev_converter = node.document.converter)
-          prev_converter = nil
-        else
-          node.document.instance_variable_set :@converter, self
-        end
-        if node.blocks?
-          node.content
-        elsif node.content_model != :compound && (string = node.content)
-          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
-      end
-
-      def log severity, message = nil, &block
-        logger.send severity, message, &block unless scratch?
-      end
-
       def convert_document doc
         doc.promote_preface_block
         init_pdf doc
@@ -195,15 +171,18 @@ module Asciidoctor
         # NOTE: a new page will already be started (page_number = 2) if the front cover image is a PDF
         ink_cover_page doc, :front
         has_front_cover = page_number > marked_page_number
-        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: 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
+        if (has_title_page = (title_page_on = doc.doctype == 'book' || (doc.attr? 'title-page')) && (start_title_page doc))
+          # NOTE: the base font must be set before any content is written to the main or scratch document
+          font @theme.base_font_family, size: @root_font_size, style: @theme.base_font_style
+          ink_title_page doc
+          start_new_page
+        else
+          @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: 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
+        end
 
         unless title_page_on
           body_start_page_number = page_number
@@ -217,14 +196,14 @@ module Asciidoctor
         indent_section do
           toc_num_levels = (doc.attr 'toclevels', 2).to_i
           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?
+            start_toc_page doc, toc_placement if title_page_on
             add_dest_for_block doc, id: 'toc', y: (at_page_top? ? page_height : nil)
             @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')
+          start_new_page if @ppbook && verso_page? && !(((next_block = doc.first_child)&.context == :preamble ? next_block.first_child : next_block)&.option? 'nonfacing')
 
           if title_page_on
             zero_page_offset = has_front_cover ? 1 : 0
@@ -383,7 +362,7 @@ module Asciidoctor
           @ppbook = nil
         end
         # QUESTION: should ThemeLoader handle registering fonts instead?
-        register_fonts theme.font_catalog, (doc.attr 'pdf-fontsdir', 'GEM_FONTS_DIR')
+        register_fonts theme.font_catalog, ((doc.attr 'pdf-fontsdir')&.sub '{docdir}', (doc.attr 'docdir')) || 'GEM_FONTS_DIR'
         default_kerning theme.base_font_kerning != 'none'
         @fallback_fonts = Array theme.font_fallbacks
         @allow_uri_read = doc.attr? 'allow-uri-read'
@@ -405,12 +384,13 @@ module Asciidoctor
         @font_scale = 1
         @font_color = theme.base_font_color
         @text_decoration_width = theme.base_text_decoration_width
-        @base_text_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_text_align
+        @base_text_align = (text_align = doc.attr 'text-align') && (TextAlignmentNames.include? text_align) ? text_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') &&
+        if (hyphen_lang = (doc.attr 'hyphens') ||
+            (((doc.attribute_locked? 'hyphens') || ((doc.instance_variable_get :@attributes_modified).include? 'hyphens')) ? nil : @theme.base_hyphens)) &&
             ((defined? ::Text::Hyphen::VERSION) || !(Helpers.require_library 'text/hyphen', 'text-hyphen', :warn).nil?)
-          hyphen_lang = doc.attr 'lang' if hyphen_lang.empty?
+          hyphen_lang = doc.attr 'lang' if !(::String === hyphen_lang) || hyphen_lang.empty?
           hyphen_lang = 'en_us' if hyphen_lang.nil_or_empty? || hyphen_lang == 'en'
           hyphen_lang = (hyphen_lang.tr '-', '_').downcase
           @hyphenator = ::Text::Hyphen.new language: hyphen_lang
@@ -434,75 +414,10 @@ module Asciidoctor
         if (@optimize = doc.attr 'optimize')
           @optimize = nil unless (defined? ::Asciidoctor::PDF::Optimizer) || !(Helpers.require_library OptimizerRequirePath, 'rghost', :warn).nil? # rubocop:disable Style/SoleNestedConditional
         end
-        allocate_prototype
+        allocate_scratch_prototype
         self
       end
 
-      def load_theme doc
-        @theme ||= begin # rubocop:disable Naming/MemoizedInstanceVariableName
-          if (theme = doc.options[:pdf_theme])
-            theme = theme.dup
-            @themesdir = ::File.expand_path theme.__dir__ || (doc.attr 'pdf-themesdir') || ::Dir.pwd
-          elsif (theme_name = doc.attr 'pdf-theme')
-            theme = ThemeLoader.load_theme theme_name, (user_themesdir = doc.attr 'pdf-themesdir')
-            @themesdir = theme.__dir__
-          else
-            @themesdir = (theme = ThemeLoader.load_theme).__dir__
-          end
-          prepare_theme theme
-        rescue
-          if user_themesdir
-            message = %(could not locate or load the pdf theme `#{theme_name}' in #{user_themesdir})
-          else
-            message = %(could not locate or load the built-in pdf theme `#{theme_name}')
-          end
-          message += %( because of #{$!.class} #{$!.message})
-          log :error, (message.sub %r/$/, '; reverting to default theme')
-          @themesdir = (theme = ThemeLoader.load_theme).__dir__
-          prepare_theme theme
-        end
-      end
-
-      def prepare_theme theme
-        theme.base_font_color ||= '000000'
-        theme.base_font_size ||= 12
-        theme.base_font_style = theme.base_font_style&.to_sym || :normal
-        theme.page_numbering_start_at ||= 'body'
-        theme.running_content_start_at ||= 'body'
-        theme.heading_margin_page_top ||= 0
-        theme.heading_margin_top ||= 0
-        theme.heading_margin_bottom ||= 0
-        theme.prose_text_indent ||= 0
-        theme.prose_text_indent_inner ||= 0
-        theme.prose_margin_bottom ||= 0
-        theme.block_margin_bottom ||= 0
-        theme.list_indent ||= 0
-        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
-        theme.role_unresolved_font_color ||= 'FF0000'
-        theme.footnotes_item_spacing ||= 0
-        theme.index_columns ||= 2
-        theme.index_column_gap ||= theme.base_font_size
-        theme.kbd_separator ||= '+'
-        theme.title_page_authors_delimiter ||= ', '
-        theme.title_page_revision_delimiter ||= ', '
-        theme.toc_indent ||= 0
-        theme.toc_hanging_indent ||= 0
-        if ::Array === (quotes = theme.quotes)
-          TypographicQuotes.each_with_index {|char, idx| quotes[idx] ||= char }
-        else
-          theme.quotes = TypographicQuotes
-        end
-        theme
-      end
-
       def build_pdf_options doc, theme
         case (page_margin = (doc.attr 'pdf-page-margin') || theme.page_margin)
         when ::Array
@@ -620,35 +535,86 @@ module Asciidoctor
         info
       end
 
-      # NOTE: init_page is called within a float context; this will suppress prawn-svg messing with the cursor
-      # NOTE: init_page is not called for imported pages, front and back cover pages, and other image pages
-      def init_page *_args
-        next_page_side = page_side nil, @folio_placement[:inverted]
-        if @media == 'prepress' && (next_page_margin = @page_margin_by_side[page_number == 1 ? :cover : next_page_side]) != page_margin
-          set_page_margin next_page_margin
+      def load_theme doc
+        @theme ||= begin # rubocop:disable Naming/MemoizedInstanceVariableName
+          if (theme = doc.options[:pdf_theme])
+            theme = theme.dup
+            @themesdir = ::File.expand_path theme.__dir__ ||
+              (user_themesdir = ((doc.attr 'pdf-themesdir')&.sub '{docdir}', (doc.attr 'docdir')) || ::Dir.pwd)
+          elsif (theme_name = doc.attr 'pdf-theme')
+            theme = ThemeLoader.load_theme theme_name, (user_themesdir = (doc.attr 'pdf-themesdir')&.sub '{docdir}', (doc.attr 'docdir'))
+            @themesdir = theme.__dir__
+          else
+            @themesdir = (theme = ThemeLoader.load_theme).__dir__
+          end
+          prepare_theme theme
+        rescue
+          if user_themesdir
+            message = %(could not locate or load the pdf theme `#{theme_name}' in #{user_themesdir})
+          else
+            message = %(could not locate or load the built-in pdf theme `#{theme_name}')
+          end
+          message += %( because of #{$!.class} #{$!.message})
+          log :error, (message.sub %r/$/, '; reverting to default theme')
+          @themesdir = (theme = ThemeLoader.load_theme).__dir__
+          prepare_theme theme
         end
-        unless @page_bg_color == 'FFFFFF'
-          tare = true
-          fill_absolute_bounds @page_bg_color
+      end
+
+      def prepare_theme theme
+        theme.base_font_color ||= '000000'
+        theme.base_font_size ||= 12
+        theme.base_font_style = theme.base_font_style&.to_sym || :normal
+        theme.page_numbering_start_at ||= 'body'
+        theme.running_content_start_at ||= 'body'
+        theme.heading_margin_page_top ||= 0
+        theme.heading_margin_top ||= 0
+        theme.heading_margin_bottom ||= 0
+        theme.prose_text_indent ||= 0
+        theme.prose_text_indent_inner ||= 0
+        theme.prose_margin_bottom ||= 0
+        theme.block_margin_bottom ||= 0
+        theme.list_indent ||= 0
+        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
+        theme.role_unresolved_font_color ||= 'FF0000'
+        theme.footnotes_item_spacing ||= 0
+        theme.index_columns ||= 2
+        theme.index_column_gap ||= theme.base_font_size
+        theme.kbd_separator ||= '+'
+        theme.title_page_authors_delimiter ||= ', '
+        theme.title_page_revision_delimiter ||= ', '
+        theme.toc_indent ||= 0
+        theme.toc_hanging_indent ||= 0
+        if ::Array === (quotes = theme.quotes)
+          TypographicQuotes.each_with_index {|char, idx| quotes[idx] ||= char }
+        else
+          theme.quotes = TypographicQuotes
         end
-        if (bg_image_path, bg_image_opts = @page_bg_image[next_page_side])
-          tare = true
-          begin
-            if bg_image_opts[:format] == 'pdf'
-              # NOTE: pages that use PDF for the background do not support a background color or running content
-              # IMPORTANT: the background PDF must have the same dimensions as the current PDF
-              import_page bg_image_path, (bg_image_opts.merge replace: true, advance: false, advance_if_missing: false)
-            else
-              canvas { image bg_image_path, ({ position: :center, vposition: :center }.merge bg_image_opts) }
-            end
-          rescue
-            facing_page_side = (PageSides - [next_page_side])[0]
-            @page_bg_image[facing_page_side] = nil if @page_bg_image[facing_page_side] == @page_bg_image[next_page_side]
-            @page_bg_image[next_page_side] = nil
-            log :warn, %(could not embed page background image: #{bg_image_path}; #{$!.message})
-          end
+        theme
+      end
+
+      def indent_section
+        if (values = @section_indent)
+          indent(values[0], values[1]) { yield }
+        else
+          yield
+        end
+      end
+
+      def outdent_section enabled = true
+        if enabled && (values = @section_indent)
+          indent(-values[0], -values[1]) { yield }
+        else
+          yield
         end
-        page.tare_content_stream if tare
       end
 
       def convert_section sect, _opts = {}
@@ -657,7 +623,7 @@ module Asciidoctor
           sect.context = :open
           return convert_abstract sect
         elsif (index_section = sectname == 'index') && @index.empty?
-          sect.parent.blocks.delete sect
+          sect.remove
           return
         end
 
@@ -668,10 +634,10 @@ module Asciidoctor
           title = %(#{title}\n<em class="subtitle">#{subtitle}</em>)
         end
         hlevel = sect.level.next
-        align = (@theme[%(heading_h#{hlevel}_text_align)] || @theme.heading_text_align || @base_text_align).to_sym
+        text_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))
         hidden = sect.option? 'notitle'
-        hopts = { align: align, level: hlevel, part: part, chapterlike: chapterlike, outdent: !(part || chapterlike) }
+        hopts = { align: text_align, level: hlevel, part: part, chapterlike: chapterlike, outdent: !(part || chapterlike) }
         if part
           unless @theme.heading_part_break_before == 'auto'
             started_new = true
@@ -684,7 +650,7 @@ module Asciidoctor
             start_new_chapter sect
           end
         end
-        arrange_heading sect, title, hopts unless hidden || started_new || at_page_top? || !sect.blocks?
+        arrange_heading sect, title, hopts unless hidden || started_new || at_page_top? || sect.empty?
         # 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?
@@ -710,58 +676,14 @@ module Asciidoctor
         sect.set_attr 'pdf-page-end', page_number
       end
 
-      def indent_section
-        if (values = @section_indent)
-          indent(values[0], values[1]) { yield }
-        else
-          yield
-        end
-      end
-
-      def outdent_section enabled = true
-        if enabled && (values = @section_indent)
-          indent(-values[0], -values[1]) { yield }
-        else
-          yield
-        end
-      end
-
-      # QUESTION: if a footnote ref appears in a separate chapter, should the footnote def be duplicated?
-      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
-        with_dry_run do |extent|
-          if (single_page_height = extent&.single_page_height) && (delta = cursor - single_page_height - 0.0001) > 0
-            move_down delta
-          end
-          theme_font :footnotes do
-            (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')
-            fns.each do |fn|
-              label = (index = fn.index) - index_offset
-              if sect_xreftext
-                fn.singleton_class.send :attr_accessor, :label unless fn.respond_to? :label=
-                fn.label = %(#{label} - #{sect_xreftext})
-              end
-              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
-        end
-        nil
-      end
-
       def convert_floating_title node
         title = node.title
         hlevel = node.level.next
-        unless (align = resolve_text_align_from_role node.roles)
-          align = (@theme[%(heading_h#{hlevel}_text_align)] || @theme.heading_text_align || @base_text_align).to_sym
+        unless (text_align = resolve_text_align_from_role node.roles)
+          text_align = (@theme[%(heading_h#{hlevel}_text_align)] || @theme.heading_text_align || @base_text_align).to_sym
         end
-        hopts = { align: align, level: hlevel, outdent: (parent = node.parent).context == :section }
-        arrange_heading node, title, hopts unless at_page_top? || node == parent.blocks[-1]
+        hopts = { align: text_align, level: hlevel, outdent: node.parent.context == :section }
+        arrange_heading node, title, hopts unless at_page_top? || node.last_child?
         add_dest_for_block node if node.id
         # QUESTION: should we decouple styles from section titles?
         theme_font :heading, level: hlevel do
@@ -769,26 +691,84 @@ module Asciidoctor
         end
       end
 
-      def convert_abstract node
-        add_dest_for_block node if node.id
-        outdent_section do
-          pad_box @theme.abstract_padding do
-            theme_font :abstract_title do
-              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_text_align || @base_text_align).to_sym, hyphenate: true }
-              if (text_indent = @theme.prose_text_indent) > 0
-                prose_opts[:indent_paragraphs] = text_indent
-              end
-              # FIXME: allow theme to control more first line options
-              if (line1_font_style = @theme.abstract_first_line_font_style&.to_sym) && line1_font_style != font_style
-                case line1_font_style
-                when :normal
-                  first_line_options = { styles: [] }
-                when :normal_italic
-                  first_line_options = { styles: [:italic] }
-                else
+      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, spacer: @theme.index_column_gap do
+          @index.categories.each do |category|
+            bounds.move_past_bottom if space_needed_for_category > cursor
+            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, pagenum_sequence_style }
+            @theme.prose_margin_bottom > cursor ? bounds.move_past_bottom : (move_down @theme.prose_margin_bottom)
+          end
+        end
+        nil
+      end
+
+      def convert_index_list_item term, pagenum_sequence_style = nil
+        text = escape_xml term.name
+        unless term.container?
+          if @media == 'screen'
+            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.map {|dest| dest[:page] }.uniq
+          end
+          text = %(#{text}, #{pagenums.join ', '})
+        end
+        subterm_indent = @theme.description_list_description_indent
+        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, pagenum_sequence_style
+          end
+        end unless term.leaf?
+      end
+
+      def convert_preamble node
+        # FIXME: core should not be promoting paragraph to preamble if there are no sections
+        if (first_block = node.first_child)&.context == :paragraph && node.document.sections? && !first_block.role?
+          first_block.role = 'lead'
+        end
+        traverse node
+        theme_margin :block, :bottom, (next_enclosed_block node)
+        convert_toc node, placement: 'preamble'
+      end
+
+      def convert_abstract node
+        add_dest_for_block node if node.id
+        outdent_section do
+          pad_box @theme.abstract_padding do
+            theme_font :abstract_title do
+              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_text_align || @base_text_align).to_sym, hyphenate: true }
+              if (text_indent = @theme.prose_text_indent) > 0
+                prose_opts[:indent_paragraphs] = text_indent
+              end
+              # FIXME: allow theme to control more first line options
+              if (line1_font_style = @theme.abstract_first_line_font_style&.to_sym) && line1_font_style != font_style
+                case line1_font_style
+                when :normal
+                  first_line_options = { styles: [] }
+                when :normal_italic
+                  first_line_options = { styles: [:italic] }
+                else
                   first_line_options = { styles: [font_style, line1_font_style] }
                 end
               end
@@ -801,12 +781,12 @@ module Asciidoctor
               prose_opts[:first_line_options] = first_line_options if first_line_options
               # FIXME: make this cleaner!!
               if node.blocks?
-                last_block = (blocks = node.blocks)[-1]
-                blocks.each do |child|
+                last_block = node.last_child
+                node.blocks.each do |child|
                   if child.context == :paragraph
                     child.document.playback_attributes child.attributes
                     prose_opts[:margin_bottom] = 0 if child == last_block
-                    ink_prose child.content, ((align = resolve_text_align_from_role child.roles) ? (prose_opts.merge align: align) : prose_opts.dup)
+                    ink_prose child.content, ((text_align = resolve_text_align_from_role child.roles) ? (prose_opts.merge align: text_align) : prose_opts.dup)
                     prose_opts.delete :first_line_options
                     prose_opts.delete :margin_bottom
                   else
@@ -815,8 +795,8 @@ module Asciidoctor
                   end
                 end
               elsif node.content_model != :compound && (string = node.content)
-                if (align = resolve_text_align_from_role node.roles)
-                  prose_opts[:align] = align
+                if (text_align = resolve_text_align_from_role node.roles)
+                  prose_opts[:align] = text_align
                 end
                 ink_prose string, (prose_opts.merge margin_bottom: 0)
               end
@@ -827,27 +807,16 @@ module Asciidoctor
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
-      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.role = 'lead'
-        end
-        traverse node
-        theme_margin :block, :bottom, (next_enclosed_block node)
-        convert_toc node, placement: 'preamble'
-      end
-
       def convert_paragraph node
         add_dest_for_block node if node.id
 
         prose_opts = { margin_bottom: 0, hyphenate: true }
-        if (align = resolve_text_align_from_role (roles = node.roles), query_theme: true, remove_predefined: true)
-          prose_opts[:align] = align
+        if (text_align = resolve_text_align_from_role (roles = node.roles), query_theme: true, remove_predefined: true)
+          prose_opts[:align] = text_align
         end
         role_keys = roles.map {|role| %(role_#{role}).to_sym } unless roles.empty?
         if (text_indent = @theme.prose_text_indent) > 0 ||
-            ((text_indent = @theme.prose_text_indent_inner) > 0 &&
-            (self_idx = (siblings = node.parent.blocks).index node) > 0 && siblings[self_idx - 1].context == :paragraph)
+            ((text_indent = @theme.prose_text_indent_inner) > 0 && node.previous_sibling&.context == :paragraph)
           prose_opts[:indent_paragraphs] = text_indent
         end
         if (bottom_gutter = @bottom_gutters[-1][node])
@@ -877,7 +846,7 @@ module Asciidoctor
 
       def convert_admonition node
         type = node.attr 'name'
-        label_align = @theme.admonition_label_text_align&.to_sym || :center
+        label_text_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
@@ -893,14 +862,14 @@ module Asciidoctor
             icon_size = icon_data[:size] || 24
             label_width = label_min_width || (icon_size * 1.5)
           elsif (icon_path = has_icon || !(icon_path = (@theme[%(admonition_icon_#{type})] || {})[:image]) ?
-              (resolve_icon_image_path node, type) :
+              (get_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 image#{has_icon ? '' : ' for ' + type.upcase} 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 || (get_icon_image_path node, type, false)})
           end
         end
         unless icons
@@ -927,7 +896,7 @@ module Asciidoctor
                     advance_page unless first_page
                     rule_segment_height = start_cursor = cursor
                     rule_segment_height -= last_page.cursor if last_page
-                    bounding_box [0, start_cursor], width: label_width + lpad[1], height: rule_segment_height do
+                    bounding_box [bounds.left, start_cursor], width: label_width + lpad[1], height: rule_segment_height do
                       stroke_vertical_rule rule_color, at: bounds.right, line_style: rule_style, line_width: rule_width
                     end
                   end
@@ -935,7 +904,7 @@ module Asciidoctor
               end
               float do
                 adjusted_font_size = nil
-                bounding_box [0, cursor], width: label_width, height: label_height do
+                bounding_box [bounds.left, cursor], width: label_width, height: label_height do
                   if icons == 'font'
                     # FIXME: we assume icon is square
                     icon_size = fit_icon_to_bounds icon_size
@@ -948,14 +917,14 @@ module Asciidoctor
                     end
                     icon icon_data[:name],
                       valign: label_valign,
-                      align: label_align,
+                      align: label_text_align,
                       color: (icon_data[:stroke_color] || font_color),
                       size: icon_size
                   elsif icons
                     if (::Asciidoctor::Image.format icon_path) == 'svg'
                       begin
                         svg_obj = ::Prawn::SVG::Interface.new (::File.read icon_path, mode: 'r:UTF-8'), self,
-                          position: label_align,
+                          position: label_text_align,
                           vposition: label_valign,
                           width: label_width,
                           height: label_height,
@@ -981,7 +950,7 @@ module Asciidoctor
                         if (icon_height = icon_width * (1 / icon_aspect_ratio)) > label_height
                           icon_width *= label_height / icon_height
                         end
-                        embed_image image_obj, image_info, width: icon_width, position: label_align, vposition: label_valign
+                        embed_image image_obj, image_info, width: icon_width, position: label_text_align, vposition: label_valign
                       rescue
                         log :warn, %(could not embed admonition icon image: #{icon_path}; #{$!.message})
                         icons = nil
@@ -1012,7 +981,7 @@ module Asciidoctor
                       end
                       @text_transform = nil # already applied to label
                       ink_prose label_text,
-                        align: label_align,
+                        align: label_text_align,
                         valign: label_valign,
                         line_height: 1,
                         margin: 0,
@@ -1035,12 +1004,167 @@ module Asciidoctor
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
+      # QUESTION: can we avoid arranging fragments multiple times (conums & autofit) by eagerly preparing arranger?
+      def convert_code node
+        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)
+            case highlighter
+            when 'coderay'
+              Helpers.require_library CodeRayRequirePath, 'coderay' unless defined? ::Asciidoctor::Prawn::CodeRayEncoder
+            when 'pygments'
+              Helpers.require_library PygmentsRequirePath, 'pygments.rb' unless defined? ::Pygments::Ext::BlockStyles
+            when 'rouge'
+              Helpers.require_library RougeRequirePath, 'rouge' unless defined? ::Rouge::Formatters::Prawn
+            else
+              highlighter = nil
+            end
+            prev_subs = (subs = node.subs).dup
+            callouts_enabled = subs.include? :callouts
+            highlight_idx = subs.index :highlight
+            # NOTE: scratch? here only applies if listing block is nested inside another block
+            if !highlighter || scratch?
+              highlighter = nil
+              if highlight_idx
+                # switch the :highlight sub back to :specialcharacters
+                subs[highlight_idx] = :specialcharacters
+              else
+                prev_subs = nil
+              end
+              source_string = guard_indentation node.content
+            elsif highlight_idx
+              # NOTE: the source highlighter logic below handles the highlight and callouts subs
+              subs.replace subs - [:highlight, :callouts]
+              # NOTE: indentation guards will be added by the source highlighter logic
+              source_string = expand_tabs node.content
+            else
+              highlighter = prev_subs = nil
+              source_string = guard_indentation node.content
+            end
+          else
+            highlighter = nil
+            source_string = guard_indentation node.content
+          end
+
+          case highlighter
+          when 'coderay'
+            source_string, conum_mapping = extract_conums source_string if callouts_enabled
+            srclang = node.attr 'language', 'text'
+            begin
+              ::CodeRay::Scanners[(srclang = (srclang.start_with? 'html+') ? (srclang.slice 5, srclang.length).to_sym : srclang.to_sym)]
+            rescue ::ArgumentError
+              srclang = :text
+            end
+            fragments = (::CodeRay.scan source_string, srclang).to_prawn
+            source_chunks = conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
+          when 'pygments'
+            unless (style = (node.document.attr 'pygments-style')) && (::Pygments::Ext::BlockStyles.available? style)
+              style = 'pastie'
+            end
+            # QUESTION: allow border color to be set by theme for highlighted block?
+            pg_block_styles = ::Pygments::Ext::BlockStyles.for style
+            bg_color_override = pg_block_styles[:background_color]
+            font_color_override = pg_block_styles[:font_color]
+            if source_string.empty?
+              source_chunks = []
+            else
+              lexer = (::Pygments::Lexer.find_by_alias node.attr 'language', 'text') || (::Pygments::Lexer.find_by_mimetype 'text/plain')
+              lexer_opts = { nowrap: true, noclasses: true, stripnl: false, style: style }
+              lexer_opts[:startinline] = !(node.option? 'mixed') if lexer.name == 'PHP'
+              source_string, conum_mapping = extract_conums source_string if callouts_enabled
+              # NOTE: highlight can return nil if something goes wrong; fallback to encoded source string if this happens
+              result = (lexer.highlight source_string, options: lexer_opts) || (node.apply_subs source_string, [:specialcharacters])
+              if node.attr? 'highlight'
+                if (highlight_lines = node.resolve_lines_to_highlight source_string, (node.attr 'highlight')).empty?
+                  highlight_lines = nil
+                else
+                  pg_highlight_bg_color = pg_block_styles[:highlight_background_color]
+                  highlight_lines = highlight_lines.map {|linenum| [linenum, pg_highlight_bg_color] }.to_h
+                end
+              end
+              if (node.option? 'linenums') || (node.attr? 'linenums')
+                linenums = (node.attr 'start', 1).to_i
+                postprocess = true
+                extensions << FormattedText::SourceWrap
+              elsif conum_mapping || highlight_lines
+                postprocess = true
+              end
+              fragments = text_formatter.format result
+              fragments = restore_conums fragments, conum_mapping, linenums, highlight_lines if postprocess
+              source_chunks = guard_indentation_in_fragments fragments
+            end
+          when 'rouge'
+            formatter = (@rouge_formatter ||= ::Rouge::Formatters::Prawn.new theme: (node.document.attr 'rouge-style'), line_gap: @theme.code_line_gap, highlight_background_color: @theme.code_highlight_background_color)
+            # QUESTION: allow border color to be set by theme for highlighted block?
+            bg_color_override = formatter.background_color
+            if source_string.empty?
+              source_chunks = []
+            else
+              if (node.option? 'linenums') || (node.attr? 'linenums')
+                formatter_opts = { line_numbers: true, start_line: (node.attr 'start', 1).to_i }
+                extensions << FormattedText::SourceWrap
+              else
+                formatter_opts = {}
+              end
+              if (srclang = node.attr 'language')
+                if srclang.include? '?'
+                  if (lexer = ::Rouge::Lexer.find_fancy srclang) && lexer.tag == 'php' && !(node.option? 'mixed') && !((lexer_opts = lexer.options).key? 'start_inline')
+                    lexer = lexer.class.new lexer_opts.merge 'start_inline' => true
+                  end
+                elsif (lexer = ::Rouge::Lexer.find srclang)
+                  lexer = lexer.new start_inline: true if lexer.tag == 'php' && !(node.option? 'mixed')
+                end
+              end
+              lexer ||= ::Rouge::Lexers::PlainText
+              source_string, conum_mapping = extract_conums source_string if callouts_enabled
+              if (node.attr? 'highlight') && !(hl_lines = (node.resolve_lines_to_highlight source_string, (node.attr 'highlight'))).empty?
+                formatter_opts[:highlight_lines] = hl_lines.map {|linenum| [linenum, true] }.to_h
+              end
+              fragments = formatter.format (lexer.lex source_string), formatter_opts rescue [text: source_string]
+              source_chunks = conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
+            end
+          else
+            # NOTE: only format if we detect a need (callouts or inline formatting)
+            source_chunks = (XMLMarkupRx.match? source_string) ? (text_formatter.format source_string) : [text: source_string]
+          end
+          node.subs.replace prev_subs if prev_subs
+          adjusted_font_size = ((node.option? 'autofit') || (node.document.attr? 'autofit-option')) ? (compute_autofit_font_size source_chunks, :code) : nil
+        end
+
+        caption_below = @theme.code_caption_end&.to_sym == :bottom
+        arrange_block node do |extent|
+          add_dest_for_block node if node.id
+          tare_first_page_content_stream do
+            theme_fill_and_stroke_block :code, extent, background_color: bg_color_override, caption_node: caption_below ? nil : node
+          end
+          pad_box @theme.code_padding, node do
+            theme_font :code do
+              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,
+                bottom_gutter: @bottom_gutters[-1][node],
+                extensions: extensions.empty? ? nil : extensions
+            end
+          end
+        end
+        # TODO: add protection against the bottom caption being widowed
+        ink_caption node, category: :code, end: :bottom if caption_below
+        theme_margin :block, :bottom, (next_enclosed_block node)
+      end
+
+      alias convert_listing convert_code
+      alias convert_literal convert_code
+      alias convert_listing_or_literal convert_code
+
       def convert_example node
         return convert_open node if node.option? 'collapsible'
+        caption_bottom = @theme.example_caption_end&.to_sym == :bottom
         arrange_block node do |extent|
-          add_dest_for_block node if node.id # Q: do we want to put anchor above top margin instead?
+          add_dest_for_block node if node.id
           tare_first_page_content_stream do
-            theme_fill_and_stroke_block :example, extent, caption_node: node
+            theme_fill_and_stroke_block :example, extent, caption_node: caption_bottom ? nil : node
           end
           pad_box @theme.example_padding, node do
             theme_font :example do
@@ -1048,6 +1172,8 @@ module Asciidoctor
             end
           end
         end
+        # TODO: add protection against the bottom caption being widowed
+        ink_caption node, category: :example, end: :bottom if caption_bottom
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
@@ -1097,7 +1223,7 @@ module Asciidoctor
                 advance_page unless first_page
                 b_height = start_cursor = cursor
                 b_height -= last_page.cursor if last_page
-                bounding_box [0, start_cursor], width: bounds.width, height: b_height do
+                bounding_box [bounds.left, start_cursor], width: bounds.width, height: b_height do
                   stroke_vertical_rule b_color, line_width: b_left_width, at: b_left_width * 0.5
                 end
               end
@@ -1118,7 +1244,7 @@ module Asciidoctor
               end
             end
             if attribution
-              margin_bottom @theme.block_margin_bottom
+              theme_margin :block, :bottom
               theme_font %(#{category}_cite) do
                 attribution_parts = citetitle ? [attribution, citetitle] : [attribution]
                 ink_prose %(#{EmDash} #{attribution_parts.join ', '}), align: :left, normalize: false, margin_bottom: 0
@@ -1152,7 +1278,7 @@ module Asciidoctor
       end
 
       def convert_colist node
-        unless at_page_top? || (self_idx = (siblings = node.parent.blocks).index node) == 0 || !([:listing, :literal].include? siblings[self_idx - 1].context)
+        if !at_page_top? && ((prev_context = node.previous_sibling&.context) == :listing || prev_context == :literal)
           margin_top @theme.callout_list_margin_top_after_code
         end
         add_dest_for_block node if node.id
@@ -1160,8 +1286,8 @@ module Asciidoctor
         last_item = node.items[-1]
         item_spacing = @theme.callout_list_item_spacing || @theme.list_item_spacing
         item_opts = { margin_bottom: item_spacing, normalize_line_height: true }
-        if (item_align = (resolve_text_align_from_role node.roles) || @theme.list_text_align&.to_sym)
-          item_opts[:align] = item_align
+        if (item_text_align = (resolve_text_align_from_role node.roles) || @theme.list_text_align&.to_sym)
+          item_opts[:align] = item_text_align
         end
         theme_font :callout_list do
           line_metrics = theme_font(:conum) { calc_line_metrics @base_line_height }
@@ -1181,7 +1307,7 @@ module Asciidoctor
         theme_font :conum do
           marker_width = rendered_width_of_string %(#{marker = conum_glyph index}x)
           float do
-            bounding_box [0, cursor], width: marker_width do
+            bounding_box [bounds.left, cursor], width: marker_width do
               ink_prose marker, align: :center, inline_format: false, margin: 0
             end
           end
@@ -1379,13 +1505,13 @@ module Asciidoctor
         ink_caption node, category: :list, labeled: false if node.title?
 
         opts = {}
-        if (align = resolve_text_align_from_role node.roles)
-          opts[:align] = align
+        if (text_align = resolve_text_align_from_role node.roles)
+          opts[:align] = text_align
         elsif node.style == 'bibliography'
           opts[:align] = :left
-        elsif (align = @theme.list_text_align&.to_sym) # rubocop:disable Lint/DuplicateBranch
+        elsif (text_align = @theme.list_text_align&.to_sym) # rubocop:disable Lint/DuplicateBranch
           # NOTE: theme setting only affects alignment of list text (not nested blocks)
-          opts[:align] = align
+          opts[:align] = text_align
         end
 
         line_metrics = calc_line_metrics @base_line_height
@@ -1469,7 +1595,7 @@ module Asciidoctor
               character_spacing_correction = 0.5 if (rendered_width_of_char 'x', character_spacing: -0.5) == marker_gap
             end
             marker_height = height_of_typeset_text marker, line_height: marker_style[:line_height], single_line: true
-            start_position = -marker_width + -marker_gap + character_spacing_correction
+            start_position = bounds.left - marker_width - marker_gap + character_spacing_correction
             float do
               advance_page if @media == 'prepress' && cursor < marker_height
               flow_bounding_box position: start_position, width: marker_width do
@@ -1498,30 +1624,18 @@ module Asciidoctor
         traverse_list_item node, list_type, opts
       end
 
-      def traverse_list_item node, list_type, opts = {}
-        if list_type == :dlist # qanda
-          terms, desc = node
-          terms.each {|term| ink_prose %(<em>#{term.text}</em>), (opts.merge margin_bottom: @theme.description_list_term_spacing) }
-          if desc
-            ink_prose desc.text, (opts.merge hyphenate: true) if desc.text?
-            traverse desc
-          end
-        else
-          if (primary_text = node.text).nil_or_empty?
-            ink_prose DummyText, opts unless node.blocks?
-          else
-            ink_prose primary_text, (opts.merge hyphenate: true)
+      def convert_image node, opts = {}
+        target, image_format = (node.extend ::Asciidoctor::Image).target_and_format
+
+        unless image_format == 'pdf'
+          if (float_to = node.attr 'float') && ((BlockFloatNames.include? float_to) ? float_to : (float_to = nil))
+            alignment = float_to.to_sym
+          elsif (alignment = node.attr 'align')
+            alignment = (BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left
+          elsif !(alignment = node.roles.reverse.find {|r| BlockAlignmentNames.include? r }&.to_sym)
+            alignment = @theme.image_align&.to_sym || :left
           end
-          traverse node
         end
-      end
-
-      def allocate_space_for_list_item line_metrics
-        advance_page if !at_page_top? && cursor < line_metrics.height + line_metrics.leading + line_metrics.padding_top
-      end
-
-      def convert_image node, opts = {}
-        target, image_format = (node.extend ::Asciidoctor::Image).target_and_format
 
         if image_format == 'gif' && !(defined? ::GMagick::Image)
           log :warn, %(GIF image format not supported. Install the prawn-gmagick gem or convert #{target} to PNG.)
@@ -1570,15 +1684,8 @@ module Asciidoctor
           end
         end
 
-        return on_image_error :missing, node, target, opts unless image_path
+        return on_image_error :missing, node, target, (opts.merge align: alignment) unless image_path
 
-        if (float_to = node.attr 'float') && ((BlockFloatNames.include? float_to) ? float_to : (float_to = nil))
-          alignment = float_to.to_sym
-        elsif (alignment = node.attr 'align')
-          alignment = (BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left
-        else
-          alignment = (resolve_text_align_from_role node.roles) || @theme.image_align&.to_sym || :left
-        end
         # 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
@@ -1635,7 +1742,7 @@ module Asciidoctor
               svg_obj.document.warnings.each do |img_warning|
                 log :warn, %(problem encountered in image: #{image_path}; #{img_warning})
               end unless scratch?
-              draw_image_border image_cursor, rendered_w, rendered_h, alignment unless node.role? && (node.has_role? 'noborder')
+              draw_image_border image_cursor, rendered_w, rendered_h, alignment unless pinned || (node.role? && (node.has_role? 'noborder'))
               if (link = node.attr 'link')
                 add_link_to_image link, { width: rendered_w, height: rendered_h }, position: alignment, y: image_y
               end
@@ -1664,7 +1771,7 @@ module Asciidoctor
               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')
+              draw_image_border image_cursor, rendered_w, rendered_h, alignment unless pinned || (node.role? && (node.has_role? 'noborder'))
               if (link = node.attr 'link')
                 add_link_to_image link, { width: rendered_w, height: rendered_h }, position: alignment, y: image_y
               end
@@ -1682,65 +1789,8 @@ module Asciidoctor
           end
         rescue => e
           raise if ::StopIteration === e
-          on_image_error :exception, node, target, (opts.merge message: %(could not embed image: #{image_path}; #{e.message}#{::Prawn::Errors::UnsupportedImageType === e && !(defined? ::GMagick::Image) ? '; install prawn-gmagick gem to add support' : ''}))
-        end
-      end
-
-      def supports_float_wrapping? node
-        node.context == :paragraph
-      end
-
-      def init_float_box _node, block_width, block_height, float_to
-        gap = ::Array === (gap = @theme.image_float_gap) ? gap.dup : [gap, gap]
-        float_w = block_width + (gap[0] ||= 12)
-        float_h = block_height + (gap[1] ||= 6)
-        box_l = bounds.left + (float_to == 'right' ? 0 : float_w)
-        box_t = cursor + block_height
-        box_w = bounds.width - float_w
-        box_r = box_l + box_w
-        box_h = [box_t, float_h].min
-        box_b = box_t - box_h
-        move_cursor_to box_t
-        @float_box = { page: page_number, top: box_t, right: box_r, bottom: box_b, left: box_l, width: box_w, height: box_h, gap: gap }
-      end
-
-      def draw_image_border top, w, h, alignment
-        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
-            bb_x = (bounds.width - w) * 0.5
-          elsif alignment == :right
-            bb_x = bounds.width - w
-          end
-          bounding_box [(bb_x || 0), top], width: (bb_width || w), height: h, position: alignment do
-            theme_fill_and_stroke_bounds :image
-          end
-          true
-        end
-      end
-
-      def on_image_error _reason, node, target, opts
-        log :warn, opts[:message] if opts.key? :message
-        alt_text_vars = { alt: (node.attr 'alt'), target: target }
-        alt_text_template = @theme.image_alt_content || '%{link}[%{alt}]%{/link} | <em>%{target}</em>' # rubocop:disable Style/FormatStringToken
-        return if alt_text_template.empty?
-        if (link = node.attr 'link')
-          alt_text_vars[:link] = %(<a href="#{link}">)
-          alt_text_vars[:'/link'] = '</a>'
-        else
-          alt_text_vars[:link] = ''
-          alt_text_vars[:'/link'] = ''
+          on_image_error :exception, node, target, (opts.merge align: alignment, message: %(could not embed image: #{image_path}; #{e.message}#{::Prawn::Errors::UnsupportedImageType === e && !(defined? ::GMagick::Image) ? '; install prawn-gmagick gem to add support' : ''}))
         end
-        theme_font :image_alt do
-          alignment = (alignment = node.attr 'align') ?
-            ((BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left) :
-            (resolve_text_align_from_role node.roles) || (@theme.image_align&.to_sym || :left)
-          ink_prose alt_text_template % alt_text_vars, align: alignment, margin: 0, normalize: false, single_line: true
-        end
-        ink_caption node, category: :image, end: :bottom if node.title?
-        theme_margin :block, :bottom, (next_enclosed_block node) unless opts[:pinned]
-        nil
       end
 
       def convert_audio node
@@ -1789,158 +1839,28 @@ module Asciidoctor
         end
       end
 
-      # QUESTION: can we avoid arranging fragments multiple times (conums & autofit) by eagerly preparing arranger?
-      def convert_code node
-        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)
-            case highlighter
-            when 'coderay'
-              Helpers.require_library CodeRayRequirePath, 'coderay' unless defined? ::Asciidoctor::Prawn::CodeRayEncoder
-            when 'pygments'
-              Helpers.require_library PygmentsRequirePath, 'pygments.rb' unless defined? ::Pygments::Ext::BlockStyles
-            when 'rouge'
-              Helpers.require_library RougeRequirePath, 'rouge' unless defined? ::Rouge::Formatters::Prawn
-            else
-              highlighter = nil
-            end
-            prev_subs = (subs = node.subs).dup
-            callouts_enabled = subs.include? :callouts
-            highlight_idx = subs.index :highlight
-            # NOTE: scratch? here only applies if listing block is nested inside another block
-            if !highlighter || scratch?
-              highlighter = nil
-              if highlight_idx
-                # switch the :highlight sub back to :specialcharacters
-                subs[highlight_idx] = :specialcharacters
-              else
-                prev_subs = nil
-              end
-              source_string = guard_indentation node.content
-            elsif highlight_idx
-              # NOTE: the source highlighter logic below handles the highlight and callouts subs
-              subs.replace subs - [:highlight, :callouts]
-              # NOTE: indentation guards will be added by the source highlighter logic
-              source_string = expand_tabs node.content
-            else
-              highlighter = prev_subs = nil
-              source_string = guard_indentation node.content
-            end
-          else
-            highlighter = nil
-            source_string = guard_indentation node.content
-          end
-
-          case highlighter
-          when 'coderay'
-            source_string, conum_mapping = extract_conums source_string if callouts_enabled
-            srclang = node.attr 'language', 'text'
-            begin
-              ::CodeRay::Scanners[(srclang = (srclang.start_with? 'html+') ? (srclang.slice 5, srclang.length).to_sym : srclang.to_sym)]
-            rescue ::ArgumentError
-              srclang = :text
-            end
-            fragments = (::CodeRay.scan source_string, srclang).to_prawn
-            source_chunks = conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
-          when 'pygments'
-            unless (style = (node.document.attr 'pygments-style')) && (::Pygments::Ext::BlockStyles.available? style)
-              style = 'pastie'
-            end
-            # QUESTION: allow border color to be set by theme for highlighted block?
-            pg_block_styles = ::Pygments::Ext::BlockStyles.for style
-            bg_color_override = pg_block_styles[:background_color]
-            font_color_override = pg_block_styles[:font_color]
-            if source_string.empty?
-              source_chunks = []
-            else
-              lexer = (::Pygments::Lexer.find_by_alias node.attr 'language', 'text') || (::Pygments::Lexer.find_by_mimetype 'text/plain')
-              lexer_opts = { nowrap: true, noclasses: true, stripnl: false, style: style }
-              lexer_opts[:startinline] = !(node.option? 'mixed') if lexer.name == 'PHP'
-              source_string, conum_mapping = extract_conums source_string if callouts_enabled
-              # NOTE: highlight can return nil if something goes wrong; fallback to encoded source string if this happens
-              result = (lexer.highlight source_string, options: lexer_opts) || (node.apply_subs source_string, [:specialcharacters])
-              if node.attr? 'highlight'
-                if (highlight_lines = node.resolve_lines_to_highlight source_string, (node.attr 'highlight')).empty?
-                  highlight_lines = nil
-                else
-                  pg_highlight_bg_color = pg_block_styles[:highlight_background_color]
-                  highlight_lines = highlight_lines.map {|linenum| [linenum, pg_highlight_bg_color] }.to_h
-                end
-              end
-              if (node.option? 'linenums') || (node.attr? 'linenums')
-                linenums = (node.attr 'start', 1).to_i
-                postprocess = true
-                extensions << FormattedText::SourceWrap
-              elsif conum_mapping || highlight_lines
-                postprocess = true
-              end
-              fragments = text_formatter.format result
-              fragments = restore_conums fragments, conum_mapping, linenums, highlight_lines if postprocess
-              source_chunks = guard_indentation_in_fragments fragments
-            end
-          when 'rouge'
-            formatter = (@rouge_formatter ||= ::Rouge::Formatters::Prawn.new theme: (node.document.attr 'rouge-style'), line_gap: @theme.code_line_gap, highlight_background_color: @theme.code_highlight_background_color)
-            # QUESTION: allow border color to be set by theme for highlighted block?
-            bg_color_override = formatter.background_color
-            if source_string.empty?
-              source_chunks = []
-            else
-              if (node.option? 'linenums') || (node.attr? 'linenums')
-                formatter_opts = { line_numbers: true, start_line: (node.attr 'start', 1).to_i }
-                extensions << FormattedText::SourceWrap
-              else
-                formatter_opts = {}
-              end
-              if (srclang = node.attr 'language')
-                if srclang.include? '?'
-                  if (lexer = ::Rouge::Lexer.find_fancy srclang) && lexer.tag == 'php' && !(node.option? 'mixed') && !((lexer_opts = lexer.options).key? 'start_inline')
-                    lexer = lexer.class.new lexer_opts.merge 'start_inline' => true
-                  end
-                elsif (lexer = ::Rouge::Lexer.find srclang)
-                  lexer = lexer.new start_inline: true if lexer.tag == 'php' && !(node.option? 'mixed')
-                end
-              end
-              lexer ||= ::Rouge::Lexers::PlainText
-              source_string, conum_mapping = extract_conums source_string if callouts_enabled
-              if (node.attr? 'highlight') && !(hl_lines = (node.resolve_lines_to_highlight source_string, (node.attr 'highlight'))).empty?
-                formatter_opts[:highlight_lines] = hl_lines.map {|linenum| [linenum, true] }.to_h
-              end
-              fragments = formatter.format (lexer.lex source_string), formatter_opts rescue [text: source_string]
-              source_chunks = conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
-            end
-          else
-            # NOTE: only format if we detect a need (callouts or inline formatting)
-            source_chunks = (XMLMarkupRx.match? source_string) ? (text_formatter.format source_string) : [text: source_string]
+      # NOTE: to insert sequential page breaks, you must put {nbsp} between page breaks
+      def convert_page_break node
+        if (page_layout = node.attr 'page-layout').nil_or_empty?
+          unless node.role? && (page_layout = (node.roles.map(&:to_sym) & PageLayouts)[-1])
+            page_layout = nil
           end
-          node.subs.replace prev_subs if prev_subs
-          adjusted_font_size = ((node.option? 'autofit') || (node.document.attr? 'autofit-option')) ? (compute_autofit_font_size source_chunks, :code) : nil
+        elsif !(PageLayouts.include? (page_layout = page_layout.to_sym))
+          page_layout = nil
         end
 
-        arrange_block node do |extent|
-          add_dest_for_block node if node.id
-          tare_first_page_content_stream do
-            theme_fill_and_stroke_block :code, extent, background_color: bg_color_override, caption_node: node
-          end
-          pad_box @theme.code_padding, node do
-            theme_font :code do
-              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,
-                bottom_gutter: @bottom_gutters[-1][node],
-                extensions: extensions.empty? ? nil : extensions
-            end
+        if at_page_top?
+          if page_layout && page_layout != page.layout && page.empty?
+            delete_current_page
+            advance_page layout: page_layout
           end
+        elsif page_layout
+          advance_page layout: page_layout
+        else
+          advance_page
         end
-
-        theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
-      alias convert_listing convert_code
-      alias convert_literal convert_code
-      alias convert_listing_or_literal convert_code
-
       def convert_pass node
         theme_font :code do
           typeset_formatted_text [text: (guard_indentation node.content), color: @theme.base_font_color], (calc_line_metrics @base_line_height)
@@ -1963,100 +1883,14 @@ module Asciidoctor
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
-      # Extract callout marks from string, indexed by 0-based line number
-      # Return an Array with the processed string as the first argument
-      # and the mapping of lines to conums as the second.
-      def extract_conums string
-        conum_mapping = {}
-        auto_num = 0
-        string = (string.split LF).map.with_index do |line, line_num|
-          # FIXME: we get extra spaces before numbers if more than one on a line
-          if line.include? '<'
-            line = line.gsub CalloutExtractRx do
-              # honor the escape
-              if $1 == ?\\
-                $&.sub $1, ''
-              else
-                (conum_mapping[line_num] ||= []) << ($3 == '.' ? (auto_num += 1) : $3.to_i)
-                ''
-              end
-            end
-            # NOTE: use first position to store space that precedes conums
-            if (conum_mapping.key? line_num) && (line.end_with? ' ')
-              trimmed_line = line.rstrip
-              conum_mapping[line_num].unshift line.slice trimmed_line.length, line.length
-              line = trimmed_line
-            end
-          end
-          line
-        end.join LF
-        conum_mapping = nil if conum_mapping.empty?
-        [string, conum_mapping]
-      end
-
-      # Restore the conums into the Array of formatted text fragments
-      #--
-      # QUESTION: can this be done more efficiently?
-      # QUESTION: can we reuse arrange_fragments_by_line?
-      def restore_conums fragments, conum_mapping, linenums = nil, highlight_lines = nil
-        lines = []
-        line_num = 0
-        # reorganize the fragments into an array of lines
-        fragments.each do |fragment|
-          line = (lines[line_num] ||= [])
-          if (text = fragment[:text]) == LF
-            lines[line_num += 1] ||= []
-          elsif text.include? LF
-            (text.split LF, -1).each_with_index do |line_in_fragment, idx|
-              line = (lines[line_num += 1] ||= []) unless idx == 0
-              line << (fragment.merge text: line_in_fragment) unless line_in_fragment.empty?
-            end
-          else
-            line << fragment
-          end
-        end
-        conum_font_color = @theme.conum_font_color
-        if (conum_font_name = @theme.conum_font_family) == font_name
-          conum_font_name = nil
-        end
-        last_line_num = lines.size - 1
-        if linenums
-          pad_size = (last_line_num + 1).to_s.length
-          linenum_color = @theme.code_linenum_font_color
-        end
-        # append conums to appropriate lines, then flatten to an array of fragments
-        lines.flat_map.with_index do |line, cur_line_num|
-          last_line = cur_line_num == last_line_num
-          visible_line_num = cur_line_num + (linenums || 1)
-          if highlight_lines && (highlight_bg_color = highlight_lines[visible_line_num])
-            line.unshift text: DummyText, background_color: highlight_bg_color, highlight: true, inline_block: true, extend: true, width: 0, callback: [FormattedText::TextBackgroundAndBorderRenderer]
-          end
-          line.unshift text: %(#{visible_line_num.to_s.rjust pad_size} ), linenum: visible_line_num, color: linenum_color if linenums
-          if conum_mapping && (conums = conum_mapping.delete cur_line_num)
-            line << { text: conums.shift } if ::String === conums[0]
-            conum_text = conums.map {|num| conum_glyph num }.join ' '
-            conum_fragment = { text: conum_text }
-            conum_fragment[:color] = conum_font_color if conum_font_color
-            conum_fragment[:font] = conum_font_name if conum_font_name
-            line << conum_fragment
-          end
-          line << { text: LF } unless last_line
-          line
-        end
-      end
-
-      def conum_glyph number
-        @conum_glyphs[number - 1]
-      end
-
-      def convert_table node
-        if !at_page_top? && ((unbreakable = node.option? 'unbreakable') || ((node.option? 'breakable') && (node.id || node.title?)))
-          (table_container = Block.new (table_dup = node.dup), :open) << table_dup
-          if unbreakable
-            table_dup.remove_attr 'unbreakable-option'
-            table_container.set_attr 'unbreakable-option'
-          else
-            table_dup.remove_attr 'breakable-option'
+      def convert_table node
+        if !at_page_top? && ((unbreakable = node.option? 'unbreakable') || ((node.option? 'breakable') && (node.id || node.title?)))
+          (table_container = Block.new (table_dup = node.dup), :open) << table_dup
+          if unbreakable
+            table_dup.remove_attr 'unbreakable-option'
+            table_container.set_attr 'unbreakable-option'
+          else
+            table_dup.remove_attr 'breakable-option'
           end
           table_container.id, table_dup.id = table_dup.id, nil
           if table_dup.title?
@@ -2428,10 +2262,7 @@ module Asciidoctor
         return if @toc_extent
         is_macro = (placement = opts[:placement] || 'macro') == 'macro'
         if ((doc = node.document).attr? 'toc-placement', placement) && (doc.attr? 'toc') && doc.sections?
-          if (is_book = doc.doctype == 'book')
-            start_new_page unless at_page_top?
-            start_new_page if @ppbook && verso_page? && !(is_macro && (node.option? 'nonfacing'))
-          end
+          start_toc_page node, placement if (is_book = doc.doctype == 'book')
           add_dest_for_block node, id: (node.id || 'toc') if is_macro
           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'
@@ -2443,74 +2274,42 @@ module Asciidoctor
         nil
       end
 
-      # NOTE: to insert sequential page breaks, you must put {nbsp} between page breaks
-      def convert_page_break node
-        if (page_layout = node.attr 'page-layout').nil_or_empty?
-          unless node.role? && (page_layout = (node.roles.map(&:to_sym) & PageLayouts)[-1])
-            page_layout = nil
-          end
-        elsif !(PageLayouts.include? (page_layout = page_layout.to_sym))
-          page_layout = nil
-        end
-
-        if at_page_top?
-          if page_layout && page_layout != page.layout && page.empty?
-            delete_current_page
-            advance_page layout: page_layout
-          end
-        elsif page_layout
-          advance_page layout: page_layout
+      def traverse node, opts = {}
+        # NOTE: need to reconfigure document to use scratch converter in scratch document
+        if self == (prev_converter = node.document.converter)
+          prev_converter = nil
         else
-          advance_page
+          node.document.instance_variable_set :@converter, self
         end
-      end
-
-      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, spacer: @theme.index_column_gap do
-          @index.categories.each do |category|
-            bounds.move_past_bottom if space_needed_for_category > cursor
-            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, pagenum_sequence_style }
-            @theme.prose_margin_bottom > cursor ? bounds.move_past_bottom : (move_down @theme.prose_margin_bottom)
+        if node.blocks?
+          node.content
+        elsif node.content_model != :compound && (string = node.content)
+          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
-        nil
+      ensure
+        node.document.instance_variable_set :@converter, prev_converter if prev_converter
       end
 
-      def convert_index_list_item term, pagenum_sequence_style = nil
-        text = escape_xml term.name
-        unless term.container?
-          if @media == 'screen'
-            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
+      def traverse_list_item node, list_type, opts = {}
+        if list_type == :dlist # qanda
+          terms, desc = node
+          terms.each {|term| ink_prose %(<em>#{term.text}</em>), (opts.merge margin_bottom: @theme.description_list_term_spacing) }
+          if desc
+            ink_prose desc.text, (opts.merge hyphenate: true) if desc.text?
+            traverse desc
+          end
+        else
+          if (primary_text = node.text).nil_or_empty?
+            ink_prose DummyText, opts unless node.blocks?
           else
-            pagenums = consolidate_ranges term.dests.map {|dest| dest[:page] }.uniq
+            ink_prose primary_text, (opts.merge hyphenate: true)
           end
-          text = %(#{text}, #{pagenums.join ', '})
+          traverse node
         end
-        subterm_indent = @theme.description_list_description_indent
-        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, pagenum_sequence_style
-          end
-        end unless term.leaf?
       end
 
       def convert_inline_anchor node
@@ -2792,193 +2591,118 @@ module Asciidoctor
         node.id ? %(<a id="#{node.id}">#{DummyText}</a>#{quoted_text}) : quoted_text
       end
 
-      # 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
+      # If an id is provided or the node passed as the first argument has an id,
+      # add a named destination to the document equivalent to the node id at the
+      # current y position. If the node does not have an id and an id is not
+      # specified, do nothing.
+      #
+      # If the node is a section, and the current y position is the top of the
+      # page, set the y position equal to the page height to improve the navigation
+      # experience. If the current x position is at or inside the left margin, set
+      # the x position equal to 0 (left edge of page) to improve the navigation
+      # experience.
+      def add_dest_for_block node, id: nil, y: nil
+        if !scratch? && (id ||= node.id)
+          dest_x = bounds.absolute_left.truncate 4
+          # QUESTION: when content is aligned to left margin, should we keep precise x value or just use 0?
+          dest_x = 0 if dest_x <= page_margin_left
+          unless (dest_y = y)
+            dest_y = @y
+            dest_y += [page_height - dest_y, -@theme.block_anchor_top.to_f].min
+          end
+          # TODO: find a way to store only the ref of the destination; look it up when we need it
+          node.set_attr 'pdf-destination', (node_dest = (dest_xyz dest_x, dest_y))
+          add_dest id, node_dest
+        end
+        nil
+      end
 
-        # NOTE: a new page may have already been started at this point, so decide what to do with it
-        if page.empty?
-          page.reset_content if (recycle = @ppbook ? recto_page? : true)
-        elsif @ppbook && page_number > 0 && recto_page?
-          start_new_page
+      def add_outline doc, num_levels, toc_page_nums, num_front_matter_pages, has_front_cover
+        if ::String === num_levels
+          if num_levels.include? ':'
+            num_levels, expand_levels = num_levels.split ':', 2
+            num_levels = num_levels.empty? ? (doc.attr 'toclevels', 2).to_i : num_levels.to_i
+            expand_levels = expand_levels.to_i
+          else
+            num_levels = expand_levels = num_levels.to_i
+          end
+        else
+          expand_levels = num_levels
         end
+        front_matter_counter = RomanNumeral.new 0, :lower
+        pagenum_labels = {}
 
-        side = page_side (recycle ? nil : page_number + 1), @folio_placement[:inverted]
-        prev_bg_image = @page_bg_image[side]
-        prev_bg_color = @page_bg_color
-        if (bg_image = resolve_background_image doc, @theme, 'title-page-background-image')
-          @page_bg_image[side] = bg_image[0] && bg_image
+        num_front_matter_pages.times do |n|
+          pagenum_labels[n] = { P: (::PDF::Core::LiteralString.new front_matter_counter.next!.to_s) }
         end
-        if (bg_color = resolve_theme_color :title_page_background_color)
-          @page_bg_color = bg_color
+
+        # add labels for each content page, which is required for reader's page navigator to work correctly
+        (num_front_matter_pages..(page_count - 1)).each_with_index do |n, i|
+          pagenum_labels[n] = { P: (::PDF::Core::LiteralString.new (i + 1).to_s) }
         end
-        recycle ? float { init_page self } : start_new_page
-        @page_bg_image[side] = prev_bg_image if bg_image
-        @page_bg_color = prev_bg_color if bg_color
 
-        # NOTE: this is the first page created, so we must set the base font
-        font @theme.base_font_family, size: @root_font_size, style: @theme.base_font_style
+        unless toc_page_nums.none? || (toc_title = doc.attr 'toc-title').nil_or_empty?
+          toc_section = insert_toc_section doc, toc_title, toc_page_nums
+        end
 
-        # QUESTION: allow alignment per element on title page?
-        title_align = (@theme.title_page_text_align || @base_text_align).to_sym
+        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 && (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
+        end if doc.attr? 'outline'
 
-        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
-            logo_image_attrs = (AttributeList.new $2).parse %w(alt width height)
-            if logo_image_from_theme
-              relative_to_imagesdir = false
-              logo_image_path = apply_subs_discretely doc, $1, subs: [:attributes]
-              logo_image_path = ThemeLoader.resolve_theme_asset logo_image_path, @themesdir unless doc.is_uri? logo_image_path
-            else
-              relative_to_imagesdir = true
-              logo_image_path = $1
+        toc_section&.remove
+
+        catalog.data[:PageLabels] = state.store.ref Nums: pagenum_labels.flatten
+        primary_page_mode, secondary_page_mode = PageModes[(doc.attr 'pdf-page-mode') || @theme.page_mode]
+        catalog.data[:PageMode] = primary_page_mode
+        catalog.data[:NonFullScreenPageMode] = secondary_page_mode if secondary_page_mode
+        nil
+      end
+
+      def add_outline_level outline, sections, num_levels, expand_levels
+        sections.each do |sect|
+          next if (num_levels_for_sect = (sect.attr 'outlinelevels', num_levels).to_i) < (level = sect.level) ||
+            ((sect.option? 'notitle') && sect == sect.document.last_child && sect.empty?)
+          sect_title = sanitize sect.numbered_title formal: true
+          sect_destination = sect.attr 'pdf-destination'
+          if level < num_levels_for_sect && sect.sections?
+            outline.section sect_title, destination: sect_destination, closed: expand_levels < 1 do
+              add_outline_level outline, sect.sections, num_levels_for_sect, (expand_levels - 1)
             end
           else
-            logo_image_attrs = {}
-            relative_to_imagesdir = false
-            if logo_image_from_theme
-              logo_image_path = apply_subs_discretely doc, logo_image_path, subs: [:attributes]
-              logo_image_path = ThemeLoader.resolve_theme_asset logo_image_path, @themesdir unless doc.is_uri? logo_image_path
-            end
-          end
-          if (::Asciidoctor::Image.target_and_format logo_image_path)[1] == 'pdf'
-            log :error, %(PDF format not supported for title page logo image: #{logo_image_path})
-          else
-            logo_image_attrs['target'] = logo_image_path
-            # NOTE: at the very least, title_align will be a valid alignment value
-            logo_image_attrs['align'] = [(logo_image_attrs.delete 'align'), @theme.title_page_logo_align, title_align.to_s].find {|val| (BlockAlignmentNames.include? val) }
-            if (logo_image_top = logo_image_attrs['top'] || @theme.title_page_logo_top)
-              initial_y, @y = @y, (resolve_top logo_image_top)
-            end
-            # NOTE: pinned option keeps image on same page
-            indent (@theme.title_page_logo_margin_left || 0), (@theme.title_page_logo_margin_right || 0) do
-              # FIXME: add API to Asciidoctor for creating blocks outside of extensions
-              convert_image (::Asciidoctor::Block.new doc, :image, content_model: :empty, attributes: logo_image_attrs), relative_to_imagesdir: relative_to_imagesdir, pinned: true
-            end
-            @y = initial_y if initial_y
-          end
-        end
-
-        # TODO: prevent content from spilling to next page
-        theme_font :title_page do
-          if (title_top = @theme.title_page_title_top)
-            @y = resolve_top title_top
-          end
-          unless @theme.title_page_title_display == 'none'
-            doctitle = doc.doctitle partition: true
-            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
-                ink_prose doctitle.main, align: title_align, margin: 0
-              end
-            end
-            move_down @theme.title_page_title_margin_bottom || 0
-          end
-          if @theme.title_page_subtitle_display != 'none' && (subtitle = (doctitle || (doc.doctitle partition: true)).subtitle)
-            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
-                ink_prose subtitle, align: title_align, margin: 0
-              end
-            end
-            move_down @theme.title_page_subtitle_margin_bottom || 0
-          end
-          if @theme.title_page_authors_display != 'none' && (doc.attr? 'authors')
-            move_down @theme.title_page_authors_margin_top || 0
-            indent (@theme.title_page_authors_margin_left || 0), (@theme.title_page_authors_margin_right || 0) do
-              generic_authors_content = @theme.title_page_authors_content
-              authors_content = {
-                name_only: @theme.title_page_authors_content_name_only || generic_authors_content,
-                with_email: @theme.title_page_authors_content_with_email || generic_authors_content,
-                with_url: @theme.title_page_authors_content_with_url || generic_authors_content,
-              }
-              authors = doc.authors.map.with_index do |author, idx|
-                with_author doc, author, idx == 0 do
-                  author_content_key = (url = doc.attr 'url') ? ((url.start_with? 'mailto:') ? :with_email : :with_url) : :name_only
-                  if (author_content = authors_content[author_content_key])
-                    apply_subs_discretely doc, author_content, drop_lines_with_unresolved_attributes: true, imagesdir: @themesdir
-                  else
-                    doc.attr 'author'
-                  end
-                end
-              end.join @theme.title_page_authors_delimiter
-              theme_font :title_page_authors do
-                ink_prose authors, align: title_align, margin: 0, normalize: true
-              end
-            end
-            move_down @theme.title_page_authors_margin_bottom || 0
-          end
-          unless @theme.title_page_revision_display == 'none' || (revision_info = [(doc.attr? 'revnumber') ? %(#{doc.attr 'version-label'} #{doc.attr 'revnumber'}) : nil, (doc.attr 'revdate')].compact).empty?
-            move_down @theme.title_page_revision_margin_top || 0
-            revision_text = revision_info.join @theme.title_page_revision_delimiter
-            if (revremark = doc.attr 'revremark')
-              revision_text = %(#{revision_text}: #{revremark})
-            end
-            indent (@theme.title_page_revision_margin_left || 0), (@theme.title_page_revision_margin_right || 0) do
-              theme_font :title_page_revision do
-                ink_prose revision_text, align: title_align, margin: 0, normalize: false
-              end
-            end
-            move_down @theme.title_page_revision_margin_bottom || 0
+            outline.page title: sect_title, destination: sect_destination
           end
         end
-
-        ink_prose DummyText, margin: 0, line_height: 1, normalize: false if page.empty?
-        true
       end
 
-      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?
-            go_to_page page_count if face == :back
-            start_new_page_discretely
-            # NOTE: open graphics state to prevent page from being reused
-            open_graphics_state if face == :front
-            return
-          elsif image_path == '~'
-            @page_margin_by_side[:cover] = @page_margin_by_side[:recto] if @media == 'prepress'
-            return
-          end
-
-          go_to_page page_count if face == :back
-          if image_opts[:format] == 'pdf'
-            import_page image_path, (image_opts.merge advance: face != :back, advance_if_missing: false)
-          else
-            begin
-              image_page image_path, image_opts
-            rescue
-              log :warn, %(could not embed #{face} cover image: #{image_path}; #{$!.message})
-            end
-          end
+      def apply_subs_discretely doc, value, opts = {}
+        if (imagesdir = opts[:imagesdir])
+          imagesdir_to_restore = doc.attr 'imagesdir'
+          doc.set_attr 'imagesdir', imagesdir
         end
-      end
-
-      def stamp_foreground_image doc, has_front_cover
-        pages = state.pages
-        if (first_page = (has_front_cover ? (pages.slice 1, pages.size) : pages).find {|it| !it.imported_page? }) &&
-            (first_page_num = (pages.index first_page) + 1) &&
-            (fg_image = resolve_background_image doc, @theme, 'page-foreground-image') && fg_image[0]
-          go_to_page first_page_num
-          create_stamp 'foreground-image' do
-            canvas { image fg_image[0], ({ position: :center, vposition: :center }.merge fg_image[1]) }
-          end
-          stamp 'foreground-image'
-          (first_page_num.next..page_count).each do |num|
-            go_to_page num
-            stamp 'foreground-image' unless page.imported_page?
+        # FIXME: get sub_attributes to handle drop-line w/o a warning
+        doc.set_attr 'attribute-missing', 'skip' unless (attribute_missing = doc.attr 'attribute-missing') == 'skip'
+        value = value.gsub '\{', '\\\\\\{' if (escaped_attr_ref = value.include? '\{')
+        value = (subs = opts[:subs]) ? (doc.apply_subs value, subs) : (doc.apply_subs value)
+        value = (value.split LF).delete_if {|line| SimpleAttributeRefRx.match? line }.join LF if opts[:drop_lines_with_unresolved_attributes] && (value.include? '{')
+        value = value.gsub '\{', '{' if escaped_attr_ref
+        doc.set_attr 'attribute-missing', attribute_missing unless attribute_missing == 'skip'
+        if imagesdir
+          if imagesdir_to_restore
+            doc.set_attr 'imagesdir', imagesdir_to_restore
+          else
+            doc.remove_attr 'imagesdir'
           end
         end
+        value
       end
 
-      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 ink_chapter_title
-        start_new_page if @ppbook && verso_page? && !(chapter.option? 'nonfacing')
-      end
-
-      alias start_new_part start_new_chapter
-
       # Position the cursor for where to ink the specified section title or discrete heading node.
       #
       # This method computes whether there is enough room on the page to prevent the specified node
@@ -3001,12 +2725,10 @@ module Asciidoctor
             end
             if page == start_page
               page.tare_content_stream
-              orphaned = stop_if_first_page_empty do
-                node.context == :section ? (traverse node) : (convert (siblings = node.parent.blocks)[(siblings.index node) + 1])
-              end
+              orphaned = stop_if_first_page_empty { node.context == :section ? (traverse node) : (convert node.next_sibling) }
             end
           end
-          start_new_page if orphaned
+          advance_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)]
@@ -3015,176 +2737,179 @@ module Asciidoctor
               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
-              if (min_height_after = @theme.heading_min_height_after) &&
-                  (node.context == :section ? node.blocks? : node != node.parent.blocks[-1])
+              if (min_height_after = @theme.heading_min_height_after) && (node.context == :section ? node.blocks? : !node.last_child?)
                 heading_h += min_height_after
               end
               cursor >= heading_h
             end
-            start_new_page unless h_fits
+            advance_page unless h_fits
           end
         end
         nil
       end
 
-      def ink_chapter_title node, title, opts = {}
-        ink_general_heading node, title, (opts.merge outdent: true)
+      # NOTE: only used when tabsize attribute is not specified
+      # tabs must always be replaced with spaces in order for the indentation guards to work
+      def expand_tabs string
+        if string.nil_or_empty?
+          ''
+        elsif string.include? TAB
+          full_tab_space = ' ' * (tab_size = 4)
+          (string.split LF, -1).map do |line|
+            if line.empty? || !(tab_idx = line.index TAB)
+              line
+            else
+              if tab_idx == 0
+                leading_tabs = 0
+                line.each_byte do |b|
+                  break unless b == 9
+                  leading_tabs += 1
+                end
+                line = %(#{full_tab_space * leading_tabs}#{rest = line.slice leading_tabs, line.length})
+                next line unless rest.include? TAB
+              end
+              # keeps track of how many spaces were added to adjust offset in match data
+              spaces_added = 0
+              idx = 0
+              result = ''
+              line.each_char do |c|
+                if c == TAB
+                  # calculate how many spaces this tab represents, then replace tab with spaces
+                  if (offset = idx + spaces_added) % tab_size == 0
+                    spaces_added += (tab_size - 1)
+                    result += full_tab_space
+                  else
+                    unless (spaces = tab_size - offset % tab_size) == 1
+                      spaces_added += (spaces - 1)
+                    end
+                    result += (' ' * spaces)
+                  end
+                else
+                  result += c
+                end
+                idx += 1
+              end
+              result
+            end
+          end.join LF
+        else
+          string
+        end
       end
 
-      alias ink_part_title ink_chapter_title
-
-      def ink_general_heading _node, title, opts = {}
-        ink_heading title, opts
+      # Extract callout marks from string, indexed by 0-based line number
+      # Return an Array with the processed string as the first argument
+      # and the mapping of lines to conums as the second.
+      def extract_conums string
+        conum_mapping = {}
+        auto_num = 0
+        string = (string.split LF).map.with_index do |line, line_num|
+          # FIXME: we get extra spaces before numbers if more than one on a line
+          if line.include? '<'
+            line = line.gsub CalloutExtractRx do
+              # honor the escape
+              if $1 == ?\\
+                $&.sub $1, ''
+              else
+                (conum_mapping[line_num] ||= []) << ($3 == '.' ? (auto_num += 1) : $3.to_i)
+                ''
+              end
+            end
+            # NOTE: use first position to store space that precedes conums
+            if (conum_mapping.key? line_num) && (line.end_with? ' ')
+              trimmed_line = line.rstrip
+              conum_mapping[line_num].unshift line.slice trimmed_line.length, line.length
+              line = trimmed_line
+            end
+          end
+          line
+        end.join LF
+        conum_mapping = nil if conum_mapping.empty?
+        [string, conum_mapping]
       end
 
-      # 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 h_category && (top_margin = @theme[%(#{h_category}_margin_page_top)] || @theme.heading_margin_page_top) > 0
-              move_down top_margin
+      # Restore the conums into the Array of formatted text fragments
+      #--
+      # QUESTION: can this be done more efficiently?
+      # QUESTION: can we reuse arrange_fragments_by_line?
+      def restore_conums fragments, conum_mapping, linenums = nil, highlight_lines = nil
+        lines = []
+        line_num = 0
+        # reorganize the fragments into an array of lines
+        fragments.each do |fragment|
+          line = (lines[line_num] ||= [])
+          if (text = fragment[:text]) == LF
+            lines[line_num += 1] ||= []
+          elsif text.include? LF
+            (text.split LF, -1).each_with_index do |line_in_fragment, idx|
+              line = (lines[line_num += 1] ||= []) unless idx == 0
+              line << (fragment.merge text: line_in_fragment) unless line_in_fragment.empty?
             end
-            top_margin = 0
           else
-            top_margin = (h_category ? @theme[%(#{h_category}_margin_top)] : nil) || @theme.heading_margin_top
+            line << fragment
           end
         end
-        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
+        conum_font_color = @theme.conum_font_color
+        if (conum_font_name = @theme.conum_font_family) == font_name
+          conum_font_name = nil
         end
-        outdent_section opts.delete :outdent do
-          margin_top top_margin
-          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)
+        last_line_num = lines.size - 1
+        if linenums
+          pad_size = (last_line_num + 1).to_s.length
+          linenum_color = @theme.code_linenum_font_color
+        end
+        # append conums to appropriate lines, then flatten to an array of fragments
+        lines.flat_map.with_index do |line, cur_line_num|
+          last_line = cur_line_num == last_line_num
+          visible_line_num = cur_line_num + (linenums || 1)
+          if highlight_lines && (highlight_bg_color = highlight_lines[visible_line_num])
+            line.unshift text: DummyText, background_color: highlight_bg_color, highlight: true, inline_block: true, extend: true, width: 0, callback: [FormattedText::TextBackgroundAndBorderRenderer]
           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
+          line.unshift text: %(#{visible_line_num.to_s.rjust pad_size} ), linenum: visible_line_num, color: linenum_color if linenums
+          if conum_mapping && (conums = conum_mapping.delete cur_line_num)
+            line << { text: conums.shift } if ::String === conums[0]
+            conum_text = conums.map {|num| conum_glyph num }.join ' '
+            conum_fragment = { text: conum_text }
+            conum_fragment[:color] = conum_font_color if conum_font_color
+            conum_fragment[:font] = conum_font_name if conum_font_name
+            line << conum_fragment
           end
-          margin_bottom bot_margin
+          line << { text: LF } unless last_line
+          line
         end
       end
 
-      # private
-      def ink_paragraph_in_float_box node, float_box, prose_opts, role_keys, block_next, insert_margin_bottom
-        @float_box = para_font_descender = para_font_size = end_cursor = nil
-        if role_keys
-          line_metrics = theme_font_cascade role_keys do
-            para_font_descender = font.descender
-            para_font_size = font_size
-            calc_line_metrics @base_line_height
-          end
-        else
-          para_font_descender = font.descender
-          para_font_size = font_size
-          line_metrics = calc_line_metrics @base_line_height
-        end
-        # allocate the space of at least one empty line below block
-        line_height_length = line_metrics.height + line_metrics.leading + line_metrics.padding_top
-        start_page_number = float_box[:page]
-        start_cursor = cursor
-        block_bottom = (float_box_bottom = float_box[:bottom]) + float_box[:gap][1]
-        # use :at to incorporate padding top from line metrics
-        # use :final_gap to incorporate padding bottom from line metrics
-        # use :draw_text_callback to track end cursor (requires applying :final_gap to result manually)
-        prose_opts.update \
-          at: [float_box[:left], start_cursor - line_metrics.padding_top],
-          width: float_box[:width],
-          height: [cursor, float_box[:height] - (float_box[:top] - start_cursor) + line_height_length].min,
-          final_gap: para_font_descender + line_metrics.padding_bottom,
-          draw_text_callback: (proc do |text, opts|
-            draw_text! text, opts
-            end_cursor = opts[:at][1] # does not include :final_gap value
-          end)
-        overflow_text = role_keys ?
-          theme_font_cascade(role_keys) { ink_prose node.content, prose_opts } :
-          (ink_prose node.content, prose_opts)
-        move_cursor_to end_cursor -= prose_opts[:final_gap] if end_cursor # ink_prose with :height does not move cursor
-        if overflow_text.empty?
-          if block_next && (supports_float_wrapping? block_next)
-            insert_margin_bottom.call
-            @float_box = float_box if page_number == start_page_number && cursor > start_cursor - prose_opts[:height]
-          elsif end_cursor > block_bottom
-            move_cursor_to block_bottom
-            theme_margin :block, :bottom, block_next
-          else
-            insert_margin_bottom.call
-          end
-        else
-          overflow_prose_opts = { align: prose_opts[:align] || @base_text_align.to_sym }
-          unless end_cursor
-            overflow_prose_opts[:indent_paragraphs] = prose_opts[:indent_paragraphs]
-            move_cursor_to float_box_bottom if start_cursor > float_box_bottom
-          end
-          role_keys ?
-            theme_font_cascade(role_keys) { typeset_formatted_text overflow_text, line_metrics, overflow_prose_opts } :
-            (typeset_formatted_text overflow_text, line_metrics, overflow_prose_opts)
-          insert_margin_bottom.call
-        end
+      def fallback_svg_font_name
+        @theme.svg_fallback_font_family || @theme.svg_font_family || @theme.base_font_family
       end
 
-      # NOTE: inline_format is true by default
-      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)
-          string = transform_text string, transform
-        end
-        string = hyphenate_text string, @hyphenator if (opts.delete :hyphenate) && (defined? @hyphenator)
-        # NOTE: used by extensions; ensures linked text gets formatted using the link styles
-        if (anchor = opts.delete :anchor)
-          string = anchor == true ? %(<a>#{string}</a>) : %(<a anchor="#{anchor}">#{string}</a>)
-        end
-        margin_top top_margin
-        # NOTE: normalize makes endlines soft (replaces "\n" with ' ')
-        inline_format_opts = { normalize: (opts.delete :normalize) != false }
-        if (styles = opts.delete :styles)
-          inline_format_opts[:inherited] = {
-            styles: styles,
-            text_decoration_color: (opts.delete :text_decoration_color),
-            text_decoration_width: (opts.delete :text_decoration_width),
-          }.compact
+      # Add an indentation guard at the start of indented lines.
+      # Expand tabs to spaces if tabs are present
+      def guard_indentation string
+        unless (string = expand_tabs string).empty?
+          string[0] = GuardedIndent if string.start_with? ' '
+          string.gsub! InnerIndent, GuardedInnerIndent if string.include? InnerIndent
         end
-        result = 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)
-        margin_bottom bot_margin
-        result
+        string
       end
 
-      def generate_manname_section node
-        title = node.attr 'manname-title', 'Name'
-        if (next_section_title = node.sections[0]&.title) && next_section_title.upcase == next_section_title
-          title = title.upcase
+      def guard_indentation_in_fragments fragments
+        start_of_line = true
+        fragments.each do |fragment|
+          next if (text = fragment[:text]).empty?
+          if start_of_line && (text.start_with? ' ')
+            fragment[:text] = GuardedIndent + (((text = text.slice 1, text.length).include? InnerIndent) ? (text.gsub InnerIndent, GuardedInnerIndent) : text)
+          elsif text.include? InnerIndent
+            fragment[:text] = text.gsub InnerIndent, GuardedInnerIndent
+          end
+          start_of_line = text.end_with? LF
         end
-        sect = Section.new node, 1
-        sect.sectname = 'section'
-        sect.id = node.attr 'manname-id'
-        sect.title = title
-        sect << (Block.new sect, :paragraph, source: %(#{node.attr 'manname'} - #{node.attr 'manpurpose'}), subs: :normal)
-        sect
+        fragments
+      end
+
+      def height_of_typeset_text string, opts = {}
+        line_metrics = (calc_line_metrics opts[:line_height] || @base_line_height)
+        (height_of string, leading: line_metrics.leading, final_gap: line_metrics.final_gap) + line_metrics.padding_top + (opts[:single_line] ? 0 : line_metrics.padding_bottom)
       end
 
       # Render the caption in the current document. If the dry_run option is true, return the height.
@@ -3277,7 +3002,7 @@ module Asciidoctor
           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)]
+            fill_at = [bounds.left, cursor + (margin[:top] || 0)]
             float { bounding_box(fill_at, width: container_width, height: caption_height) { fill_bounds bg_color } }
           end
           indent(*indent_by) do
@@ -3299,389 +3024,148 @@ module Asciidoctor
         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, title_page_on
-        toc_start_page_number = page_number
-        to_page = nil
-        extent = dry_run onto: self do
-          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 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
-        extent
+      def ink_chapter_title node, title, opts = {}
+        ink_general_heading node, title, (opts.merge outdent: true)
       end
 
-      def get_entries_for_toc node
-        node.sections
-      end
+      alias ink_part_title ink_chapter_title
 
-      # NOTE: num_front_matter_pages not used during a dry run
-      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_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
+      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?
+            go_to_page page_count if face == :back
+            start_new_page_discretely
+            # NOTE: open graphics state to prevent page from being reused
+            open_graphics_state if face == :front
+            return
+          elsif image_path == '~'
+            @page_margin_by_side[:cover] = @page_margin_by_side[:recto] if @media == 'prepress'
+            return
           end
-        end
-        # QUESTION: should we skip this whole method if num_levels < 0?
-        unless num_levels < 0
-          dot_leader = theme_font :toc do
-            # TODO: we could simplify by using nested theme_font :toc_dot_leader
-            if (dot_leader_font_style = @theme.toc_dot_leader_font_style&.to_sym || :normal) != font_style
-              font_style dot_leader_font_style
+
+          go_to_page page_count if face == :back
+          if image_opts[:format] == 'pdf'
+            import_page image_path, (image_opts.merge advance: face != :back, advance_if_missing: false)
+          else
+            begin
+              image_page image_path, image_opts
+            rescue
+              log :warn, %(could not embed #{face} cover image: #{image_path}; #{$!.message})
             end
-            font_size @theme.toc_dot_leader_font_size
-            {
-              font_color: @theme.toc_dot_leader_font_color || @font_color,
-              font_style: dot_leader_font_style,
-              font_size: font_size,
-              levels: ((dot_leader_l = @theme.toc_dot_leader_levels) == 'none' ? ::Set.new :
-                  (dot_leader_l && dot_leader_l != 'all' ? dot_leader_l.to_s.split.map(&:to_i).to_set : (0..num_levels).to_set)),
-              text: (dot_leader_text = @theme.toc_dot_leader_content || DotLeaderTextDefault),
-              width: dot_leader_text.empty? ? 0 : (rendered_width_of_string dot_leader_text),
-              # TODO: spacer gives a little bit of room between dots and page number
-              spacer: { text: NoBreakSpace, size: (spacer_font_size = @font_size * 0.25) },
-              spacer_width: (rendered_width_of_char NoBreakSpace, size: spacer_font_size),
-            }
           end
-          theme_margin :toc, :top
-          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)))
-        go_to_page page_count unless scratch?
-        toc_page_numbers
       end
 
-      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
-        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 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
-                ink_prose entry_title, anchor: true, normalize: false, hanging_indent: hanging_indent, normalize_line_height: true, margin: 0
-              end
-            else
-              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
-              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
-              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
-                (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
-              end
-              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? 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
-                  # NOTE: the same font is used for dot leaders throughout toc
-                  set_font toc_font_info[:font], dot_leader[:font_size]
-                  font_style dot_leader[:font_style]
-                  num_dots = [((bounds.width - start_dots - dot_leader[:spacer_width] - pgnum_label_width) / dot_leader[:width]).floor, 0].max
-                  # FIXME: dots don't line up in columns if width of page numbers differ
-                  typeset_formatted_text [
-                    { text: dot_leader[:text] * num_dots, color: dot_leader[:font_color] },
-                    dot_leader[:spacer],
-                    ({ 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: entry_anchor }], line_metrics, align: :right
+      # QUESTION: if a footnote ref appears in a separate chapter, should the footnote def be duplicated?
+      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.last_child
+        theme_margin :footnotes, :top
+        with_dry_run do |extent|
+          if (single_page_height = extent&.single_page_height) && (delta = cursor - single_page_height - 0.0001) > 0
+            move_down delta
+          end
+          theme_font :footnotes do
+            (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')
+            fns.each do |fn|
+              label = (index = fn.index) - index_offset
+              if sect_xreftext
+                fn.singleton_class.send :attr_accessor, :label unless fn.respond_to? :label=
+                fn.label = %(#{label} - #{sect_xreftext})
               end
-              move_cursor_to end_cursor
+              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
-          indent @theme.toc_indent do
-            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
+        nil
       end
 
-      # Reduce icon height to fit inside bounds.height. Icons will not render
-      # properly if they are larger than the current bounds.height.
-      def fit_icon_to_bounds preferred_size
-        (max_height = bounds.height) < preferred_size ? max_height : preferred_size
+      def ink_general_heading _node, title, opts = {}
+        ink_heading title, opts
       end
 
-      def admonition_icon_data key
-        if (icon_data = @theme[%(admonition_icon_#{key})])
-          icon_data = (AdmonitionIcons[key] || {}).merge icon_data
-          if (icon_name = icon_data[:name])
-            unless icon_name.start_with?(*IconSetPrefixes)
-              log(:info) { %(#{key} admonition in theme uses icon from deprecated fa icon set; use fas, far, or fab instead) }
-              icon_data[:name] = %(fa-#{icon_name}) unless icon_name.start_with? 'fa-'
+      # 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 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
-            icon_data[:name] = AdmonitionIcons[:note][:name]
+            top_margin = (h_category ? @theme[%(#{h_category}_margin_top)] : nil) || @theme.heading_margin_top
           end
-        else
-          (icon_data = AdmonitionIcons[key] || {})[:name] ||= AdmonitionIcons[:note][:name]
         end
-        icon_data
-      end
-
-      # 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_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_number
-
-        # FIXME: probably need to treat doctypes differently
-        is_book = doc.doctype == 'book'
-        header = doc.header? ? doc.header : nil
-        sectlevels = (@theme[%(#{periphery}_sectlevels)] || 2).to_i
-        sections = doc.find_by(context: :section) {|sect| sect.level <= sectlevels && sect != header }
-        toc_title = (doc.attr 'toc-title').to_s if (toc_page_nums = @toc_extent&.page_range)
-        disable_on_pages = @disable_running_content[periphery]
-
-        title_method = TitleStyles[@theme[%(#{periphery}_title_style)]]
-        # FIXME: we need a proper model for all this page counting
-        # FIXME: we make a big assumption that part & chapter start on new pages
-        # index parts, chapters and sections by the physical page number on which they start
-        part_start_pages = {}
-        chapter_start_pages = {}
-        section_start_pages = {}
-        trailing_section_start_pages = {}
-        sections.each do |sect|
-          pgnum = (sect.attr 'pdf-page-start').to_i
-          if is_book && ((sect_is_part = sect.sectname == 'part') || sect.level == 1)
-            if sect_is_part
-              part_start_pages[pgnum] ||= sect
+        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
+          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
-              chapter_start_pages[pgnum] ||= sect
-              # FIXME: need a better way to indicate that part has ended
-              part_start_pages[pgnum] = '' if sect.sectname == 'appendix' && !part_start_pages.empty?
+              inline_format_opts = [{ inherited: inherited }]
             end
-          else
-            trailing_section_start_pages[pgnum] = sect
-            section_start_pages[pgnum] ||= sect
-          end
-        end
-
-        # index parts, chapters, and sections by the physical page number on which they appear
-        parts_by_page = SectionInfoByPage.new title_method
-        chapters_by_page = SectionInfoByPage.new title_method
-        sections_by_page = SectionInfoByPage.new title_method
-        # QUESTION: should the default part be the doctitle?
-        last_part = nil
-        # QUESTION: should we enforce that the preamble is a preface?
-        last_chap = is_book ? :pre : nil
-        last_sect = nil
-        sect_search_threshold = 1
-        (1..num_pages).each do |pgnum|
-          if (part = part_start_pages[pgnum])
-            last_part = part
-            last_chap = nil
-            last_sect = nil
-          end
-          if (chap = chapter_start_pages[pgnum])
-            last_chap = chap
-            last_sect = nil
+            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 (sect = section_start_pages[pgnum])
-            last_sect = sect
-          elsif part || chap
-            sect_search_threshold = pgnum
-          # NOTE: we didn't find a section on this page; look back to find last section started
-          elsif last_sect
-            (sect_search_threshold..(pgnum - 1)).reverse_each do |prev|
-              if (sect = trailing_section_start_pages[prev])
-                last_sect = sect
-                break
+          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
-          parts_by_page[pgnum] = last_part
-          if toc_page_nums&.cover? pgnum
-            if is_book
-              chapters_by_page[pgnum] = toc_title
-              sections_by_page[pgnum] = nil
-            else
-              chapters_by_page[pgnum] = nil
-              sections_by_page[pgnum] = section_start_pages[pgnum] || toc_title
-            end
-            toc_page_nums = nil if toc_page_nums.end == pgnum
-          elsif last_chap == :pre
-            chapters_by_page[pgnum] = pgnum < body_start_page_number ? doc.doctitle : (doc.attr 'preface-title', 'Preface')
-            sections_by_page[pgnum] = last_sect
-          else
-            chapters_by_page[pgnum] = last_chap
-            sections_by_page[pgnum] = last_sect
-          end
+          margin_bottom bot_margin
         end
+      end
 
-        doctitle = resolve_doctitle doc, true
-        # NOTE: set doctitle again so it's properly escaped
-        doc.set_attr 'doctitle', doctitle.combined
-        doc.set_attr 'document-title', doctitle.main
-        doc.set_attr 'document-subtitle', doctitle.subtitle
-        doc.set_attr 'page-count', (num_pages - skip_pagenums)
-
-        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_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)
-          virtual_pgnum = pgnum - skip_pagenums
-          pgnum_label = (virtual_pgnum < 1 ? (RomanNumeral.new pgnum, :lower) : virtual_pgnum).to_s
-          side = page_side((@folio_placement[:basis] == :physical ? pgnum : virtual_pgnum), @folio_placement[:inverted])
-          doc.set_attr 'page-layout', page.layout.to_s
-
-          # NOTE: running content is cached per page layout
-          # QUESTION: should allocation be per side?
-          trim_styles, colspec_dict, content_dict, stamp_names = allocate_running_content_layout doc, page, periphery, periphery_layout_cache
-          # FIXME: we need to have a content setting for chapter pages
-          content_by_position, colspec_by_position = content_dict[side], colspec_dict[side]
-
-          doc.set_attr 'page-number', pgnum_label if pagenums_enabled
-          # QUESTION: should the fallback value be nil instead of empty string? or should we remove attribute if no value?
-          doc.set_attr 'part-title', ((part_info = parts_by_page[pgnum])[:title] || '')
-          if (part_numeral = part_info[:numeral])
-            doc.set_attr 'part-numeral', part_numeral
-          else
-            doc.remove_attr 'part-numeral'
-          end
-          doc.set_attr 'chapter-title', ((chap_info = chapters_by_page[pgnum])[:title] || '')
-          if (chap_numeral = chap_info[:numeral])
-            doc.set_attr 'chapter-numeral', chap_numeral
-          else
-            doc.remove_attr 'chapter-numeral'
-          end
-          doc.set_attr 'section-title', ((sect_info = sections_by_page[pgnum])[:title] || '')
-          doc.set_attr 'section-or-chapter-title', (sect_info[:title] || chap_info[:title] || '')
-
-          stamp stamp_names[side] if stamp_names
-
-          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_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
-                end
-                prev_position = nil
-                ColumnPositions.each do |position|
-                  next unless (content = content_by_position[position])
-                  next unless (colspec = colspec_by_position[position])[:width] > 0
-                  left, colwidth = colspec[:x], colspec[:width]
-                  if trim_column_rule_width && colwidth < bounds.width
-                    if (trim_column_rule = prev_position)
-                      left += (trim_column_rule_spacing * 0.5)
-                      colwidth -= trim_column_rule_spacing
-                    else
-                      colwidth -= (trim_column_rule_spacing * 0.5)
-                    end
-                  end
-                  # FIXME: we need to have a content setting for chapter pages
-                  if ::Array === content
-                    redo_with_content = nil
-                    # NOTE: float ensures cursor position is restored and returns us to current page if we overrun
-                    float do
-                      # NOTE: bounding_box is redundant if both vertical padding and border width are 0
-                      bounding_box [left, bounds.top - trim_styles[:padding][side][0] - trim_styles[:content_offset]], width: colwidth, height: trim_styles[:content_height][side] do
-                        # NOTE: image vposition respects padding; use negative image_vertical_align value to revert
-                        image_opts = content[1].merge position: colspec[:align], vposition: trim_styles[:img_valign]
-                        begin
-                          image_info = image content[0], image_opts
-                          if (image_link = content[2])
-                            image_info = { width: image_info.scaled_width, height: image_info.scaled_height } unless image_opts[:format] == 'svg'
-                            add_link_to_image image_link, image_info, image_opts
-                          end
-                        rescue
-                          redo_with_content = image_opts[:alt]
-                          log :warn, %(could not embed image in running content: #{content[0]}; #{$!.message})
-                        end
-                      end
-                    end
-                    if redo_with_content
-                      content_by_position[position] = redo_with_content
-                      redo
-                    end
-                  else
-                    theme_font %(#{periphery}_#{side}_#{position}) do
-                      # NOTE: minor optimization
-                      if content == '{page-number}'
-                        content = pagenums_enabled ? pgnum_label : nil
-                      else
-                        content = apply_subs_discretely doc, content, drop_lines_with_unresolved_attributes: true, imagesdir: @themesdir
-                        content = transform_text content, @text_transform if @text_transform
-                      end
-                      formatted_text_box (parse_text content, inline_format: [normalize: true]),
-                        at: [left, bounds.top - trim_styles[:padding][side][0] - trim_styles[:content_offset] + ((Array trim_styles[:valign])[0] == :center ? font.descender * 0.5 : 0)],
-                        color: @font_color,
-                        width: colwidth,
-                        height: trim_styles[:prose_content_height][side],
-                        align: colspec[:align],
-                        valign: trim_styles[:valign],
-                        leading: trim_styles[:line_metrics].leading,
-                        final_gap: false,
-                        overflow: :truncate
-                    end
-                  end
-                  bounding_box [colspec[:x], bounds.top - trim_styles[:padding][side][0] - trim_styles[:content_offset]], width: colspec[:width], height: trim_styles[:content_height][side] do
-                    stroke_vertical_rule trim_styles[:column_rule_color], at: bounds.left, line_style: trim_styles[:column_rule_style], line_width: trim_column_rule_width
-                  end if trim_column_rule
-                  prev_position = position
-                end
-              end
-            end
-          end
+      # NOTE: inline_format is true by default
+      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)
+          string = transform_text string, transform
         end
-
-        go_to_page prev_page_number
-        nil
+        string = hyphenate_text string, @hyphenator if (opts.delete :hyphenate) && (defined? @hyphenator)
+        # NOTE: used by extensions; ensures linked text gets formatted using the link styles
+        if (anchor = opts.delete :anchor)
+          string = anchor == true ? %(<a>#{string}</a>) : %(<a anchor="#{anchor}">#{string}</a>)
+        end
+        margin_top top_margin
+        # NOTE: normalize makes endlines soft (replaces "\n" with ' ')
+        inline_format_opts = { normalize: (opts.delete :normalize) != false }
+        if (styles = opts.delete :styles)
+          inline_format_opts[:inherited] = {
+            styles: styles,
+            text_decoration_color: (opts.delete :text_decoration_color),
+            text_decoration_width: (opts.delete :text_decoration_width),
+          }.compact
+        end
+        result = 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)
+        margin_bottom bot_margin
+        result
       end
 
       def allocate_running_content_layout doc, page, periphery, cache
@@ -3852,191 +3336,890 @@ module Asciidoctor
               end
             end
           end
-
-          [trim_styles, colspec_dict, content_dict, stamp_names]
+
+          [trim_styles, colspec_dict, content_dict, stamp_names]
+        end
+      end
+
+      # 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_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_number
+
+        # FIXME: probably need to treat doctypes differently
+        is_book = doc.doctype == 'book'
+        header = doc.header? ? doc.header : nil
+        sectlevels = (@theme[%(#{periphery}_sectlevels)] || 2).to_i
+        sections = doc.find_by(context: :section) {|sect| sect.level <= sectlevels && sect != header }
+        toc_title = (doc.attr 'toc-title').to_s if (toc_page_nums = @toc_extent&.page_range)
+        disable_on_pages = @disable_running_content[periphery]
+
+        title_method = TitleStyles[@theme[%(#{periphery}_title_style)]]
+        # FIXME: we need a proper model for all this page counting
+        # FIXME: we make a big assumption that part & chapter start on new pages
+        # index parts, chapters and sections by the physical page number on which they start
+        part_start_pages = {}
+        chapter_start_pages = {}
+        section_start_pages = {}
+        trailing_section_start_pages = {}
+        sections.each do |sect|
+          pgnum = (sect.attr 'pdf-page-start').to_i
+          if is_book && ((sect_is_part = sect.sectname == 'part') || sect.level == 1)
+            if sect_is_part
+              part_start_pages[pgnum] ||= sect
+            else
+              chapter_start_pages[pgnum] ||= sect
+              # FIXME: need a better way to indicate that part has ended
+              part_start_pages[pgnum] = '' if sect.sectname == 'appendix' && !part_start_pages.empty?
+            end
+          else
+            trailing_section_start_pages[pgnum] = sect
+            section_start_pages[pgnum] ||= sect
+          end
+        end
+
+        # index parts, chapters, and sections by the physical page number on which they appear
+        parts_by_page = SectionInfoByPage.new title_method
+        chapters_by_page = SectionInfoByPage.new title_method
+        sections_by_page = SectionInfoByPage.new title_method
+        # QUESTION: should the default part be the doctitle?
+        last_part = nil
+        # QUESTION: should we enforce that the preamble is a preface?
+        last_chap = is_book ? :pre : nil
+        last_sect = nil
+        sect_search_threshold = 1
+        (1..num_pages).each do |pgnum|
+          if (part = part_start_pages[pgnum])
+            last_part = part
+            last_chap = nil
+            last_sect = nil
+          end
+          if (chap = chapter_start_pages[pgnum])
+            last_chap = chap
+            last_sect = nil
+          end
+          if (sect = section_start_pages[pgnum])
+            last_sect = sect
+          elsif part || chap
+            sect_search_threshold = pgnum
+          # NOTE: we didn't find a section on this page; look back to find last section started
+          elsif last_sect
+            (sect_search_threshold..(pgnum - 1)).reverse_each do |prev|
+              if (sect = trailing_section_start_pages[prev])
+                last_sect = sect
+                break
+              end
+            end
+          end
+          parts_by_page[pgnum] = last_part
+          if toc_page_nums&.cover? pgnum
+            if is_book
+              chapters_by_page[pgnum] = toc_title
+              sections_by_page[pgnum] = nil
+            else
+              chapters_by_page[pgnum] = nil
+              sections_by_page[pgnum] = section_start_pages[pgnum] || toc_title
+            end
+            toc_page_nums = nil if toc_page_nums.end == pgnum
+          elsif last_chap == :pre
+            chapters_by_page[pgnum] = pgnum < body_start_page_number ? doc.doctitle : (doc.attr 'preface-title', 'Preface')
+            sections_by_page[pgnum] = last_sect
+          else
+            chapters_by_page[pgnum] = last_chap
+            sections_by_page[pgnum] = last_sect
+          end
+        end
+
+        doctitle = resolve_doctitle doc, true
+        # NOTE: set doctitle again so it's properly escaped
+        doc.set_attr 'doctitle', doctitle.combined
+        doc.set_attr 'document-title', doctitle.main
+        doc.set_attr 'document-subtitle', doctitle.subtitle
+        doc.set_attr 'page-count', (num_pages - skip_pagenums)
+
+        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_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)
+          virtual_pgnum = pgnum - skip_pagenums
+          pgnum_label = (virtual_pgnum < 1 ? (RomanNumeral.new pgnum, :lower) : virtual_pgnum).to_s
+          side = page_side((@folio_placement[:basis] == :physical ? pgnum : virtual_pgnum), @folio_placement[:inverted])
+          doc.set_attr 'page-layout', page.layout.to_s
+
+          # NOTE: running content is cached per page layout
+          # QUESTION: should allocation be per side?
+          trim_styles, colspec_dict, content_dict, stamp_names = allocate_running_content_layout doc, page, periphery, periphery_layout_cache
+          # FIXME: we need to have a content setting for chapter pages
+          content_by_position, colspec_by_position = content_dict[side], colspec_dict[side]
+
+          doc.set_attr 'page-number', pgnum_label if pagenums_enabled
+          # QUESTION: should the fallback value be nil instead of empty string? or should we remove attribute if no value?
+          doc.set_attr 'part-title', ((part_info = parts_by_page[pgnum])[:title] || '')
+          if (part_numeral = part_info[:numeral])
+            doc.set_attr 'part-numeral', part_numeral
+          else
+            doc.remove_attr 'part-numeral'
+          end
+          doc.set_attr 'chapter-title', ((chap_info = chapters_by_page[pgnum])[:title] || '')
+          if (chap_numeral = chap_info[:numeral])
+            doc.set_attr 'chapter-numeral', chap_numeral
+          else
+            doc.remove_attr 'chapter-numeral'
+          end
+          doc.set_attr 'section-title', ((sect_info = sections_by_page[pgnum])[:title] || '')
+          doc.set_attr 'section-or-chapter-title', (sect_info[:title] || chap_info[:title] || '')
+
+          stamp stamp_names[side] if stamp_names
+
+          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_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
+                end
+                prev_position = nil
+                ColumnPositions.each do |position|
+                  next unless (content = content_by_position[position])
+                  next unless (colspec = colspec_by_position[position])[:width] > 0
+                  left, colwidth = colspec[:x], colspec[:width]
+                  if trim_column_rule_width && colwidth < bounds.width
+                    if (trim_column_rule = prev_position)
+                      left += (trim_column_rule_spacing * 0.5)
+                      colwidth -= trim_column_rule_spacing
+                    else
+                      colwidth -= (trim_column_rule_spacing * 0.5)
+                    end
+                  end
+                  # FIXME: we need to have a content setting for chapter pages
+                  if ::Array === content
+                    redo_with_content = nil
+                    # NOTE: float ensures cursor position is restored and returns us to current page if we overrun
+                    float do
+                      # NOTE: bounding_box is redundant if both vertical padding and border width are 0
+                      bounding_box [left, bounds.top - trim_styles[:padding][side][0] - trim_styles[:content_offset]], width: colwidth, height: trim_styles[:content_height][side] do
+                        # NOTE: image vposition respects padding; use negative image_vertical_align value to revert
+                        image_opts = content[1].merge position: colspec[:align], vposition: trim_styles[:img_valign]
+                        begin
+                          image_info = image content[0], image_opts
+                          if (image_link = content[2])
+                            image_info = { width: image_info.scaled_width, height: image_info.scaled_height } unless image_opts[:format] == 'svg'
+                            add_link_to_image image_link, image_info, image_opts
+                          end
+                        rescue
+                          redo_with_content = image_opts[:alt]
+                          log :warn, %(could not embed image in running content: #{content[0]}; #{$!.message})
+                        end
+                      end
+                    end
+                    if redo_with_content
+                      content_by_position[position] = redo_with_content
+                      redo
+                    end
+                  else
+                    theme_font %(#{periphery}_#{side}_#{position}) do
+                      # NOTE: minor optimization
+                      if content == '{page-number}'
+                        content = pagenums_enabled ? pgnum_label : nil
+                      else
+                        content = apply_subs_discretely doc, content, drop_lines_with_unresolved_attributes: true, imagesdir: @themesdir
+                        content = transform_text content, @text_transform if @text_transform
+                      end
+                      formatted_text_box (parse_text content, inline_format: [normalize: true]),
+                        at: [left, bounds.top - trim_styles[:padding][side][0] - trim_styles[:content_offset] + ((Array trim_styles[:valign])[0] == :center ? font.descender * 0.5 : 0)],
+                        color: @font_color,
+                        width: colwidth,
+                        height: trim_styles[:prose_content_height][side],
+                        align: colspec[:align],
+                        valign: trim_styles[:valign],
+                        leading: trim_styles[:line_metrics].leading,
+                        final_gap: false,
+                        overflow: :truncate
+                    end
+                  end
+                  bounding_box [colspec[:x], bounds.top - trim_styles[:padding][side][0] - trim_styles[:content_offset]], width: colspec[:width], height: trim_styles[:content_height][side] do
+                    stroke_vertical_rule trim_styles[:column_rule_color], at: bounds.left, line_style: trim_styles[:column_rule_style], line_width: trim_column_rule_width
+                  end if trim_column_rule
+                  prev_position = position
+                end
+              end
+            end
+          end
+        end
+
+        go_to_page prev_page_number
+        nil
+      end
+
+      def ink_title_page doc
+        # QUESTION: allow alignment per element on title page?
+        title_text_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
+            logo_image_attrs = (AttributeList.new $2).parse %w(alt width height)
+            if logo_image_from_theme
+              relative_to_imagesdir = false
+              logo_image_path = apply_subs_discretely doc, $1, subs: [:attributes]
+              logo_image_path = ThemeLoader.resolve_theme_asset logo_image_path, @themesdir unless doc.is_uri? logo_image_path
+            else
+              relative_to_imagesdir = true
+              logo_image_path = $1
+            end
+          else
+            logo_image_attrs = {}
+            relative_to_imagesdir = false
+            if logo_image_from_theme
+              logo_image_path = apply_subs_discretely doc, logo_image_path, subs: [:attributes]
+              logo_image_path = ThemeLoader.resolve_theme_asset logo_image_path, @themesdir unless doc.is_uri? logo_image_path
+            end
+          end
+          if (::Asciidoctor::Image.target_and_format logo_image_path)[1] == 'pdf'
+            log :error, %(PDF format not supported for title page logo image: #{logo_image_path})
+          else
+            logo_image_attrs['target'] = logo_image_path
+            # NOTE: at the very least, title_text_align will be a valid alignment value
+            logo_image_attrs['align'] = [(logo_image_attrs.delete 'align'), @theme.title_page_logo_align, title_text_align.to_s].find {|val| (BlockAlignmentNames.include? val) }
+            if (logo_image_top = logo_image_attrs['top'] || @theme.title_page_logo_top)
+              initial_y, @y = @y, (resolve_top logo_image_top)
+            end
+            # NOTE: pinned option keeps image on same page
+            indent (@theme.title_page_logo_margin_left || 0), (@theme.title_page_logo_margin_right || 0) do
+              # FIXME: add API to Asciidoctor for creating blocks outside of extensions
+              convert_image (::Asciidoctor::Block.new doc, :image, content_model: :empty, attributes: logo_image_attrs), relative_to_imagesdir: relative_to_imagesdir, pinned: true
+            end
+            @y = initial_y if initial_y
+          end
+        end
+
+        # TODO: prevent content from spilling to next page
+        theme_font :title_page do
+          if (title_top = @theme.title_page_title_top)
+            @y = resolve_top title_top
+          end
+          unless @theme.title_page_title_display == 'none'
+            doctitle = doc.doctitle partition: true
+            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
+                ink_prose doctitle.main, align: title_text_align, margin: 0
+              end
+            end
+            move_down @theme.title_page_title_margin_bottom || 0
+          end
+          if @theme.title_page_subtitle_display != 'none' && (subtitle = (doctitle || (doc.doctitle partition: true)).subtitle)
+            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
+                ink_prose subtitle, align: title_text_align, margin: 0
+              end
+            end
+            move_down @theme.title_page_subtitle_margin_bottom || 0
+          end
+          if @theme.title_page_authors_display != 'none' && (doc.attr? 'authors')
+            move_down @theme.title_page_authors_margin_top || 0
+            indent (@theme.title_page_authors_margin_left || 0), (@theme.title_page_authors_margin_right || 0) do
+              generic_authors_content = @theme.title_page_authors_content
+              authors_content = {
+                name_only: @theme.title_page_authors_content_name_only || generic_authors_content,
+                with_email: @theme.title_page_authors_content_with_email || generic_authors_content,
+                with_url: @theme.title_page_authors_content_with_url || generic_authors_content,
+              }
+              authors = doc.authors.map.with_index do |author, idx|
+                with_author doc, author, idx == 0 do
+                  author_content_key = (url = doc.attr 'url') ? ((url.start_with? 'mailto:') ? :with_email : :with_url) : :name_only
+                  if (author_content = authors_content[author_content_key])
+                    apply_subs_discretely doc, author_content, drop_lines_with_unresolved_attributes: true, imagesdir: @themesdir
+                  else
+                    doc.attr 'author'
+                  end
+                end
+              end.join @theme.title_page_authors_delimiter
+              theme_font :title_page_authors do
+                ink_prose authors, align: title_text_align, margin: 0, normalize: true
+              end
+            end
+            move_down @theme.title_page_authors_margin_bottom || 0
+          end
+          unless @theme.title_page_revision_display == 'none' || (revision_info = [(doc.attr? 'revnumber') ? %(#{doc.attr 'version-label'} #{doc.attr 'revnumber'}) : nil, (doc.attr 'revdate')].compact).empty?
+            move_down @theme.title_page_revision_margin_top || 0
+            revision_text = revision_info.join @theme.title_page_revision_delimiter
+            if (revremark = doc.attr 'revremark')
+              revision_text = %(#{revision_text}: #{revremark})
+            end
+            indent (@theme.title_page_revision_margin_left || 0), (@theme.title_page_revision_margin_right || 0) do
+              theme_font :title_page_revision do
+                ink_prose revision_text, align: title_text_align, margin: 0, normalize: false
+              end
+            end
+            move_down @theme.title_page_revision_margin_bottom || 0
+          end
+        end
+      end
+
+      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
+          to_page = (ink_toc doc, toc_num_levels, toc_start_page_number, toc_start_cursor).end
+          theme_margin :block, :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 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
+        extent
+      end
+
+      def get_entries_for_toc node
+        node.sections
+      end
+
+      # NOTE: num_front_matter_pages not used during a dry run
+      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_text_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_text_align, level: 2, outdent: true, role: :toctitle
+          end
+        end
+        # QUESTION: should we skip this whole method if num_levels < 0?
+        unless num_levels < 0
+          dot_leader = theme_font :toc do
+            # TODO: we could simplify by using nested theme_font :toc_dot_leader
+            if (dot_leader_font_style = @theme.toc_dot_leader_font_style&.to_sym || :normal) != font_style
+              font_style dot_leader_font_style
+            end
+            font_size @theme.toc_dot_leader_font_size
+            {
+              font_color: @theme.toc_dot_leader_font_color || @font_color,
+              font_style: dot_leader_font_style,
+              font_size: font_size,
+              levels: ((dot_leader_l = @theme.toc_dot_leader_levels) == 'none' ? ::Set.new :
+                  (dot_leader_l && dot_leader_l != 'all' ? dot_leader_l.to_s.split.map(&:to_i).to_set : (0..num_levels).to_set)),
+              text: (dot_leader_text = @theme.toc_dot_leader_content || DotLeaderTextDefault),
+              width: dot_leader_text.empty? ? 0 : (rendered_width_of_string dot_leader_text),
+              # TODO: spacer gives a little bit of room between dots and page number
+              spacer: { text: NoBreakSpace, size: (spacer_font_size = @font_size * 0.25) },
+              spacer_width: (rendered_width_of_char NoBreakSpace, size: spacer_font_size),
+            }
+          end
+          theme_margin :toc, :top
+          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)))
+        go_to_page page_count unless scratch?
+        toc_page_numbers
+      end
+
+      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
+        entries.each do |entry|
+          next if (num_levels_for_entry = (entry.attr 'toclevels', num_levels).to_i) < (entry_level = entry.level + 1).pred ||
+            !(entry_anchor = (entry.attr 'pdf-anchor') || entry.id) ||
+            ((entry.option? 'notitle') && entry == entry.document.last_child && entry.empty?)
+          theme_font :toc, level: entry_level do
+            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 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
+                ink_prose entry_title, anchor: true, normalize: false, hanging_indent: hanging_indent, normalize_line_height: true, margin: 0
+              end
+            else
+              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
+              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
+              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
+                (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
+              end
+              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? 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
+                  # NOTE: the same font is used for dot leaders throughout toc
+                  set_font toc_font_info[:font], dot_leader[:font_size]
+                  font_style dot_leader[:font_style]
+                  num_dots = [((bounds.width - start_dots - dot_leader[:spacer_width] - pgnum_label_width) / dot_leader[:width]).floor, 0].max
+                  # FIXME: dots don't line up in columns if width of page numbers differ
+                  typeset_formatted_text [
+                    { text: dot_leader[:text] * num_dots, color: dot_leader[:font_color] },
+                    dot_leader[:spacer],
+                    ({ 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: entry_anchor }], line_metrics, align: :right
+              end
+              move_cursor_to end_cursor
+            end
+          end
+          indent @theme.toc_indent do
+            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
+
+      # Sends the specified message to the log unless this method is called from the scratch document
+      def log severity, message = nil, &block
+        logger.send severity, message, &block unless scratch?
+      end
+
+      # Insert a margin at the specified side if the cursor is not at the top of
+      # the page. Start a new page if amount is greater than the remaining space on
+      # the page.
+      def margin amount, _side
+        if (amount || 0) == 0 || at_page_top?
+          0
+        elsif cursor > amount
+          move_down amount
+          amount
+        else
+          # move cursor to top of next page
+          bounds.move_past_bottom
+          0
+        end
+      end
+
+      # Insert a bottom margin equal to amount unless cursor is at the top of the
+      # page (not likely). Start a new page instead if amount is greater than the
+      # remaining space on the page.
+      def margin_bottom amount
+        margin amount, :bottom
+      end
+
+      # Insert a top margin equal to amount if cursor is not at the top of the
+      # page. Start a new page instead if amount is greater than the remaining
+      # space on the page.
+      def margin_top amount
+        margin amount, :top
+      end
+
+      def next_enclosed_block block, descend: false
+        return if (context = block.context) == :document
+        parent_context = (parent = block.parent).context
+        if (list_item = context == :list_item)
+          return block.first_child if descend && block.blocks?
+          siblings = parent.items
+        else
+          siblings = parent.blocks
+        end
+        siblings = siblings.flatten if parent_context == :dlist
+        if block != siblings[-1]
+          (self_idx = siblings.index block) && siblings[self_idx + 1]
+        elsif parent_context == :list_item || (parent_context == :open && parent.style != 'abstract') || parent_context == :section
+          next_enclosed_block parent
+        elsif list_item && (grandparent = parent.parent).context == :list_item
+          next_enclosed_block grandparent
+        end
+      end
+
+      def register_fonts font_catalog, fonts_dir
+        return unless font_catalog
+        dirs = (fonts_dir.split ValueSeparatorRx, -1).map do |dir|
+          dir == 'GEM_FONTS_DIR' || dir.empty? ? ThemeLoader::FontsDir : dir
+        end
+        font_catalog.each do |key, styles|
+          styles = styles.each_with_object({}) do |(style, path), accum|
+            found = dirs.any? do |dir|
+              resolved_font_path = font_path path, dir
+              accum[style.to_sym] = resolved_font_path if ::File.readable? resolved_font_path
+            end
+            raise ::Errno::ENOENT, ((File.absolute_path? path) ? %(#{path} not found) : %(#{path} not found in #{fonts_dir.gsub ValueSeparatorRx, ' or '})) unless found
+          end
+          register_font key => styles
+        end
+      end
+
+      # Compute the rendered width of a char, taking fallback fonts into account
+      def rendered_width_of_char char, opts = {}
+        unless @fallback_fonts.empty? || (font.glyph_present? char)
+          @fallback_fonts.each do |fallback_font|
+            font fallback_font do
+              return width_of_string char, opts if font.glyph_present? char
+            end
+          end
+        end
+        width_of_string char, opts
+      end
+
+      # Compute the rendered width of a string, taking fallback fonts into account
+      def rendered_width_of_string str, opts = {}
+        opts = opts.merge kerning: default_kerning?
+        if str.length == 1
+          rendered_width_of_char str, opts
+        elsif (chars = str.each_char).all? {|char| font.glyph_present? char }
+          width_of_string str, opts
+        else
+          char_widths = chars.map {|char| rendered_width_of_char char, opts }
+          char_widths.sum + (char_widths.length * character_spacing)
+        end
+      end
+
+      # Resolve the path and sizing of the background image either from a document attribute or theme key.
+      #
+      # Returns the argument list for the image method if the document attribute or theme key is found. Otherwise,
+      # nothing. The first argument in the argument list is the image path. If that value is nil, the background
+      # image is disabled. The second argument is the options hash to specify the dimensions, such as width and fit.
+      def resolve_background_image doc, theme, key, opts = {}
+        if ::String === key
+          theme_key = opts.delete :theme_key
+          image_path = (doc.attr key) || (from_theme = theme[theme_key || (key.tr '-', '_').to_sym])
+        else
+          image_path = from_theme = theme[key]
+        end
+        symbolic_paths = opts.delete :symbolic_paths
+        if image_path
+          if symbolic_paths&.include? image_path
+            return [image_path, {}]
+          elsif image_path == 'none'
+            return []
+          elsif (image_path.include? ':') && image_path =~ ImageAttributeValueRx
+            image_attrs = (AttributeList.new $2).parse %w(alt width)
+            if from_theme
+              image_path = apply_subs_discretely doc, $1, subs: [:attributes]
+              image_relative_to = @themesdir
+            else
+              image_path = $1
+              image_relative_to = true
+            end
+          elsif from_theme
+            image_path = apply_subs_discretely doc, image_path, subs: [:attributes]
+            image_relative_to = @themesdir
+          end
+
+          image_path, image_format = ::Asciidoctor::Image.target_and_format image_path, image_attrs
+          image_path = resolve_image_path doc, image_path, image_format, image_relative_to
+
+          return unless image_path
+
+          unless ::File.readable? image_path
+            log :warn, %(#{key.to_s.tr '-_', ' '} not found or readable: #{image_path})
+            return
+          end
+
+          if image_format == 'pdf'
+            [image_path, page: [((image_attrs || {})['page']).to_i, 1].max, format: image_format]
+          else
+            [image_path, (resolve_image_options image_path, image_format, image_attrs, (({ background: true, container_size: [page_width, page_height] }.merge opts)))]
+          end
+        end
+      end
+
+      def resolve_doctitle doc, partition = nil
+        if doc.header?
+          doc.doctitle partition: partition
+        elsif partition
+          ::Asciidoctor::Document::Title.new (doc.attr 'untitled-label'), separator: (doc.attr 'title-separator')
+        else
+          doc.attr 'untitled-label'
+        end
+      end
+
+      # Resolves the explicit width, if specified, as a PDF pt value.
+      #
+      # Resolves the explicit width, first considering the pdfwidth attribute, then the scaledwidth
+      # attribute, then the theme default (if enabled by the :use_fallback option), and finally the
+      # width attribute. If the specified value is in pixels, the value is scaled by 75% to perform
+      # approximate CSS px to PDF pt conversion. If the value is a percentage, and the
+      # bounds_width option is given, the percentage of the bounds_width value is returned.
+      # Otherwise, the percentage width is returned.
+      #--
+      # QUESTION: should we enforce positive result?
+      def resolve_explicit_width attrs, opts = {}
+        bounds_width = opts[:bounds_width]
+        # QUESTION: should we restrict width to bounds_width for pdfwidth?
+        if attrs.key? 'pdfwidth'
+          if (width = attrs['pdfwidth']).end_with? '%'
+            bounds_width ? (width.to_f / 100) * bounds_width : width
+          elsif opts[:support_vw] && (width.end_with? 'vw')
+            (width.chomp 'vw').extend ViewportWidth
+          else
+            str_to_pt width
+          end
+        elsif attrs.key? 'scaledwidth'
+          # NOTE: the parser automatically appends % if value is unitless
+          if (width = attrs['scaledwidth']).end_with? '%'
+            bounds_width ? (width.to_f / 100) * bounds_width : width
+          else
+            str_to_pt width
+          end
+        elsif opts[:use_fallback] && (width = @theme.image_width)
+          if ::Numeric === width
+            width
+          elsif (width = width.to_s).end_with? '%'
+            bounds_width ? (width.to_f / 100) * bounds_width : bounds_width
+          elsif opts[:support_vw] && (width.end_with? 'vw')
+            (width.chomp 'vw').extend ViewportWidth
+          else
+            str_to_pt width
+          end
+        elsif attrs.key? 'width'
+          if (width = attrs['width']).end_with? '%'
+            width = (width.to_f / 100) * bounds_width if bounds_width
+          elsif DigitsRx.match? width
+            width = to_pt width.to_f, :px
+          else
+            return
+          end
+          bounds_width && opts[:constrain_to_bounds] ? [bounds_width, width].min : width
+        end
+      end
+
+      def resolve_image_options image_path, image_format, image_attrs, opts = {}
+        if image_format == 'svg'
+          image_opts = {
+            enable_file_requests_with_root: (::File.dirname image_path),
+            enable_web_requests: allow_uri_read ? (method :load_open_uri).to_proc : false,
+            cache_images: cache_uri,
+            fallback_font_name: fallback_svg_font_name,
+            format: 'svg',
+          }
+        else
+          image_opts = {}
+        end
+        container_size = opts[:container_size]
+        if image_attrs
+          if (alt = image_attrs['alt'])
+            image_opts[:alt] = %([#{alt}])
+          end
+          if (background = opts[:background]) && (image_pos = image_attrs['position']) && (image_pos = resolve_background_position image_pos, nil)
+            image_opts.update image_pos
+          end
+          if (image_fit = image_attrs['fit'] || (background ? 'contain' : nil))
+            image_fit = 'contain' if image_format == 'svg' && image_fit == 'fill'
+            container_width, container_height = container_size
+            case image_fit
+            when 'none'
+              if (image_width = resolve_explicit_width image_attrs, bounds_width: container_width)
+                image_opts[:width] = image_width
+              end
+            when 'scale-down'
+              # NOTE: if width and height aren't set in SVG, real width and height are computed after stretching viewbox to fit page
+              if (image_width = resolve_explicit_width image_attrs, bounds_width: container_width)
+                if image_width > container_width
+                  image_opts[:fit] = container_size
+                else
+                  image_size = intrinsic_image_dimensions image_path, image_format
+                  if image_width * (image_size[:height].to_f / image_size[:width]) > container_height
+                    image_opts[:fit] = container_size
+                  else
+                    image_opts[:width] = image_width
+                  end
+                end
+              else
+                image_size = intrinsic_image_dimensions image_path, image_format
+                image_opts[:fit] = container_size if image_size[:width] > container_width || image_size[:height] > container_height
+              end
+            when 'cover'
+              # QUESTION: should we take explicit width into account?
+              image_size = intrinsic_image_dimensions image_path, image_format
+              if container_width * (image_size[:height].to_f / image_size[:width]) < container_height
+                image_opts[:height] = container_height
+              else
+                image_opts[:width] = container_width
+              end
+            when 'fill'
+              image_opts[:width] = container_width
+              image_opts[:height] = container_height
+            else # 'contain'
+              image_opts[:fit] = container_size
+            end
+          elsif (image_width = resolve_explicit_width image_attrs, bounds_width: container_size[0])
+            image_opts[:width] = image_width
+          else # default to fit=contain if sizing is not specified
+            image_opts[:fit] = container_size
+          end
+        else
+          image_opts[:fit] = container_size
         end
+        image_opts
       end
 
-      def add_outline doc, num_levels, toc_page_nums, num_front_matter_pages, has_front_cover
-        if ::String === num_levels
-          if num_levels.include? ':'
-            num_levels, expand_levels = num_levels.split ':', 2
-            num_levels = num_levels.empty? ? (doc.attr 'toclevels', 2).to_i : num_levels.to_i
-            expand_levels = expand_levels.to_i
-          else
-            num_levels = expand_levels = num_levels.to_i
-          end
+      # Resolve the system path of the specified image path.
+      #
+      # Resolve and normalize the absolute system path of the specified image,
+      # taking into account the imagesdir attribute. If an image path is not
+      # specified, the path is read from the target attribute of the specified
+      # document node.
+      #
+      # If the target is a URI and the allow-uri-read attribute is set on the
+      # document, read the file contents to a temporary file and return the path to
+      # the temporary file. If the target is a URI and the allow-uri-read attribute
+      # is not set, or the URI cannot be read, this method returns a nil value.
+      #
+      # When a temporary file is used, the file is stored in @tmp_files to be cleaned up after conversion.
+      def resolve_image_path node, image_path, image_format, relative_to = true
+        doc = node.document
+        if relative_to == true
+          imagesdir = nil if (imagesdir = doc.attr 'imagesdir').nil_or_empty? || imagesdir == '.' || imagesdir == './'
         else
-          expand_levels = num_levels
-        end
-        front_matter_counter = RomanNumeral.new 0, :lower
-        pagenum_labels = {}
-
-        num_front_matter_pages.times do |n|
-          pagenum_labels[n] = { P: (::PDF::Core::LiteralString.new front_matter_counter.next!.to_s) }
-        end
-
-        # add labels for each content page, which is required for reader's page navigator to work correctly
-        (num_front_matter_pages..(page_count - 1)).each_with_index do |n, i|
-          pagenum_labels[n] = { P: (::PDF::Core::LiteralString.new (i + 1).to_s) }
-        end
-
-        unless toc_page_nums.none? || (toc_title = doc.attr 'toc-title').nil_or_empty?
-          toc_section = insert_toc_section doc, toc_title, toc_page_nums
+          imagesdir = relative_to
         end
-
-        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 && (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
-        end if doc.attr? 'outline'
-
-        toc_section.parent.blocks.delete toc_section if toc_section
-
-        catalog.data[:PageLabels] = state.store.ref Nums: pagenum_labels.flatten
-        primary_page_mode, secondary_page_mode = PageModes[(doc.attr 'pdf-page-mode') || @theme.page_mode]
-        catalog.data[:PageMode] = primary_page_mode
-        catalog.data[:NonFullScreenPageMode] = secondary_page_mode if secondary_page_mode
-        nil
-      end
-
-      def add_outline_level outline, sections, num_levels, expand_levels
-        sections.each do |sect|
-          next if (num_levels_for_sect = (sect.attr 'outlinelevels', num_levels).to_i) < (level = sect.level)
-          sect_title = sanitize sect.numbered_title formal: true
-          sect_destination = sect.attr 'pdf-destination'
-          if level < num_levels_for_sect && sect.sections?
-            outline.section sect_title, destination: sect_destination, closed: expand_levels < 1 do
-              add_outline_level outline, sect.sections, num_levels_for_sect, (expand_levels - 1)
-            end
-          else
-            outline.page title: sect_title, destination: sect_destination
+        # NOTE: base64 logic currently used for inline images
+        if ::Base64 === image_path
+          return @tmp_files[image_path] if @tmp_files.key? image_path
+          tmp_image = ::Tempfile.create %W(image- .#{image_format})
+          tmp_image.binmode unless image_format == 'svg'
+          tmp_image.write ::Base64.decode64 image_path
+          tmp_image.close
+          @tmp_files[image_path] = tmp_image.path
+        # NOTE: this will catch a classloader resource path on JRuby (e.g., uri:classloader:/path/to/image)
+        elsif ::File.absolute_path? image_path
+          ::File.absolute_path image_path
+        elsif !(is_uri = node.is_uri? image_path) && imagesdir && (::File.absolute_path? imagesdir)
+          ::File.absolute_path image_path, imagesdir
+        # handle case when image is a URI
+        elsif is_uri || (imagesdir && (node.is_uri? imagesdir) && (image_path = node.normalize_web_path image_path, imagesdir, false))
+          if !allow_uri_read
+            log :warn, %(cannot embed remote image: #{image_path} (allow-uri-read attribute not enabled))
+            return
+          elsif @tmp_files.key? image_path
+            return @tmp_files[image_path]
           end
-        end
-      end
-
-      def insert_toc_section doc, toc_title, toc_page_nums
-        if (doc.attr? 'toc-placement', 'macro') && (toc_node = (doc.find_by context: :toc)[0])
-          if (parent_section = toc_node.parent).context == :section
-            grandparent_section = parent_section.parent
-            toc_level = parent_section.level
-            insert_idx = (grandparent_section.blocks.index parent_section) + 1
-          else
-            grandparent_section = doc
-            toc_level = doc.sections[0].level
-            insert_idx = 0
+          tmp_image = ::Tempfile.create ['image-', image_format && %(.#{image_format})]
+          tmp_image.binmode if (binary = image_format != 'svg')
+          begin
+            load_open_uri.open_uri(image_path, (binary ? 'rb' : 'r')) {|fd| tmp_image.write fd.read }
+            tmp_image.close
+            @tmp_files[image_path] = tmp_image.path
+          rescue
+            @tmp_files[image_path] = nil
+            log :warn, %(could not retrieve remote image: #{image_path}; #{$!.message})
+            tmp_image.close
+            unlink_tmp_file tmp_image.path
+            nil
           end
-          toc_dest = toc_node.attr 'pdf-destination'
+        # handle case when image is a local file
         else
-          grandparent_section = doc
-          toc_level = doc.sections[0].level
-          insert_idx = 0
-          toc_dest = dest_top toc_page_nums.first
+          node.normalize_system_path image_path, imagesdir, nil, target_name: 'image'
         end
-        toc_section = Section.new grandparent_section, toc_level, false, attributes: { 'pdf-destination' => toc_dest }
-        toc_section.title = toc_title
-        grandparent_section.blocks.insert insert_idx, toc_section
-        toc_section
       end
 
-      def write pdf_doc, target
-        if target.respond_to? :write
-          target = ::QuantifiableStdout.new $stdout if target == $stdout
-          pdf_doc.render target
-        else
-          pdf_doc.render_file target
-          # QUESTION: restore attributes first?
-          @pdfmark&.generate_file target
-          if (quality = @optimize)
-            if quality.include? ','
-              quality, compliance = quality.split ',', 2
-            elsif quality.include? '/'
-              quality, compliance = nil, quality
+      def resolve_text_align_from_role roles, query_theme: false, remove_predefined: false
+        if (align_role = roles.reverse.find {|r| TextAlignmentRoles.include? r })
+          roles.replace roles - TextAlignmentRoles if remove_predefined
+          (align_role.slice 5, align_role.length).to_sym
+        elsif query_theme
+          roles.reverse.each do |role|
+            if (text_align = @theme[%(role_#{role}_text_align)])
+              return text_align.to_sym
             end
-            (Optimizer.new quality, pdf_doc.min_version, compliance).optimize_file target
           end
-          to_file = true
-        end
-        if !ENV['KEEP_ARTIFACTS']
-          remove_tmp_files
-        elsif to_file
-          scratch_target = (target.slice 0, target.length - (target_ext = ::File.extname target).length) + '-scratch' + target_ext
-          scratch.render_file scratch_target
+          nil
         end
-        clear_scratch
-        nil
       end
 
-      def register_fonts font_catalog, fonts_dir
-        return unless font_catalog
-        dirs = (fonts_dir.split ValueSeparatorRx, -1).map do |dir|
-          dir == 'GEM_FONTS_DIR' || dir.empty? ? ThemeLoader::FontsDir : dir
-        end
-        font_catalog.each do |key, styles|
-          styles = styles.each_with_object({}) do |(style, path), accum|
-            found = dirs.any? do |dir|
-              resolved_font_path = font_path path, dir
-              accum[style.to_sym] = resolved_font_path if ::File.readable? resolved_font_path
-            end
-            raise ::Errno::ENOENT, ((File.absolute_path? path) ? %(#{path} not found) : %(#{path} not found in #{fonts_dir.gsub ValueSeparatorRx, ' or '})) unless found
+      # Deprecated
+      alias resolve_alignment_from_role resolve_text_align_from_role
+
+      def stamp_foreground_image doc, has_front_cover
+        pages = state.pages
+        if (first_page = (has_front_cover ? (pages.slice 1, pages.size) : pages).find {|it| !it.imported_page? }) &&
+            (first_page_num = (pages.index first_page) + 1) &&
+            (fg_image = resolve_background_image doc, @theme, 'page-foreground-image') && fg_image[0]
+          go_to_page first_page_num
+          create_stamp 'foreground-image' do
+            canvas { image fg_image[0], ({ position: :center, vposition: :center }.merge fg_image[1]) }
+          end
+          stamp 'foreground-image'
+          (first_page_num.next..page_count).each do |num|
+            go_to_page num
+            stamp 'foreground-image' unless page.imported_page?
           end
-          register_font key => styles
         end
       end
 
-      def font_path font_file, fonts_dir
-        # resolve relative to built-in font dir unless path is absolute
-        ::File.absolute_path font_file, fonts_dir
+      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 ink_chapter_title
+        start_new_page if @ppbook && verso_page? && !(chapter.option? 'nonfacing')
       end
 
-      def fallback_svg_font_name
-        @theme.svg_fallback_font_family || @theme.svg_font_family || @theme.base_font_family
-      end
+      alias start_new_part start_new_chapter
 
-      def apply_text_decoration styles, category, level = nil
-        if (text_decoration_style = TextDecorationStyleTable[level && @theme[%(#{category}_h#{level}_text_decoration)] || @theme[%(#{category}_text_decoration)]])
-          {
-            styles: (styles << text_decoration_style),
-            text_decoration_color: level && @theme[%(#{category}_h#{level}_text_decoration_color)] || @theme[%(#{category}_text_decoration_color)],
-            text_decoration_width: level && @theme[%(#{category}_h#{level}_text_decoration_width)] || @theme[%(#{category}_text_decoration_width)],
-          }.compact
-        else
-          styles.empty? ? {} : { styles: styles }
-        end
-      end
+      # Returns a Boolean indicating whether the title page was created
+      def start_title_page doc
+        return unless doc.header? && !doc.notitle && @theme.title_page != false
 
-      def resolve_text_transform key, use_fallback = true
-        if (transform = ::Hash === key ? (key.delete :text_transform) : @theme[key])
-          transform == 'none' ? nil : transform
-        elsif use_fallback
-          @text_transform
+        # NOTE: a new page may have already been started at this point, so decide what to do with it
+        if page.empty?
+          page.reset_content if (recycle = @ppbook ? recto_page? : true)
+        elsif @ppbook && page_number > 0 && recto_page?
+          start_new_page
+        end
+        side = page_side (recycle ? nil : page_number + 1), @folio_placement[:inverted]
+        prev_bg_image = @page_bg_image[side]
+        prev_bg_color = @page_bg_color
+        if (bg_image = resolve_background_image doc, @theme, 'title-page-background-image')
+          @page_bg_image[side] = bg_image[0] && bg_image
         end
-      end
-
-      # 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, transparent_color = fallback_color
-        if (color = @theme[key])
-          color == 'transparent' ? transparent_color : color
-        else
-          fallback_color
+        if (bg_color = resolve_theme_color :title_page_background_color)
+          @page_bg_color = bg_color
         end
+        recycle ? float { init_page self } : start_new_page
+        @page_bg_image[side] = prev_bg_image if bg_image
+        @page_bg_color = prev_bg_color if bg_color
+        true
       end
 
-      def resolve_font_kerning keyword
-        FontKerningTable[keyword]
+      def start_toc_page node, placement
+        start_new_page unless at_page_top?
+        start_new_page if @ppbook && verso_page? && !(placement == 'macro' && (node.option? 'nonfacing'))
       end
 
-      def theme_fill_and_stroke_bounds category, opts = {}
-        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)]
+      def supports_float_wrapping? node
+        node.context == :paragraph
       end
 
       def theme_fill_and_stroke_block category, extent, opts = {}
@@ -4079,7 +4262,7 @@ module Asciidoctor
             advance_page unless first_page
             chunk_height = start_cursor = cursor
             chunk_height -= last_page.cursor if last_page
-            bounding_box [0, start_cursor], width: bounds.width, height: chunk_height do
+            bounding_box [bounds.left, start_cursor], width: bounds.width, height: chunk_height do
               theme_fill_and_stroke_bounds category, background_color: bg_color
               unless first_page
                 indent b_radius, b_radius do
@@ -4100,46 +4283,11 @@ module Asciidoctor
         nil
       end
 
-      # Insert a top margin equal to amount if cursor is not at the top of the
-      # page. Start a new page instead if amount is greater than the remaining
-      # space on the page.
-      def margin_top amount
-        margin amount, :top
-      end
-
-      # Insert a bottom margin equal to amount unless cursor is at the top of the
-      # page (not likely). Start a new page instead if amount is greater than the
-      # remaining space on the page.
-      def margin_bottom amount
-        margin amount, :bottom
-      end
-
-      # Insert a margin at the specified side if the cursor is not at the top of
-      # the page. Start a new page if amount is greater than the remaining space on
-      # the page.
-      def margin amount, _side
-        if (amount || 0) == 0 || at_page_top?
-          0
-        # NOTE: use low-level cursor calculation to workaround cursor bug in column_box context
-        elsif y - reference_bounds.absolute_bottom > amount
-          move_down amount
-          amount
-        else
-          # set cursor at top of next page
-          reference_bounds.move_past_bottom
-          0
-        end
-      end
-
-      # Lookup margin for theme element and side, then delegate to margin method.
-      # If margin value is not found, assume 0.
-      def theme_margin category, side, node = true
-        if node
-          category = :block if node != true && node.context == :section
-          margin (@theme[%(#{category}_margin_#{side})] || 0), side
-        else
-          0
-        end
+      def theme_fill_and_stroke_bounds category, opts = {}
+        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)]
       end
 
       def theme_font category, opts = {}
@@ -4198,87 +4346,15 @@ module Asciidoctor
         end
       end
 
-      # Calculate the font size (down to the minimum font size) that would allow
-      # all the specified fragments to fit in the available width without wrapping lines.
-      #
-      # Return the calculated font size if an adjustment is necessary or nil if no
-      # font size adjustment is necessary.
-      def compute_autofit_font_size fragments, category
-        arranger = arrange_fragments_by_line fragments
-        # NOTE: finalizing the line here generates fragments & calculates their widths using the current font settings
-        # NOTE: it also removes zero-width spaces
-        arranger.finalize_line
-        actual_width = width_of_fragments arranger.fragments
-        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
-            min
-          else
-            adjusted_font_size
-          end
-        end
-      end
-
-      # Arrange fragments by line in an arranger and return an unfinalized arranger.
-      #
-      # Finalizing the arranger is deferred since it must be done in the context of
-      # the global font settings you want applied to each fragment.
-      def arrange_fragments_by_line fragments, _opts = {}
-        arranger = ::Prawn::Text::Formatted::Arranger.new self
-        by_line = arranger.consumed = []
-        fragments.each do |fragment|
-          if (text = fragment[:text]) == LF || !(text.include? LF)
-            by_line << fragment
-          else
-            text.scan LineScanRx do |line|
-              by_line << (line == LF ? { text: LF } : (fragment.merge text: line))
-            end
-          end
-        end
-        arranger
-      end
-
-      # Calculate the width that is needed to print all the
-      # fragments without wrapping any lines.
-      #
-      # This method assumes endlines are represented as discrete entries in the
-      # fragments array.
-      def width_of_fragments fragments
-        line_widths = [0]
-        fragments.each do |fragment|
-          if fragment.text == LF
-            line_widths << 0
-          else
-            line_widths[-1] += fragment.width
-          end
-        end
-        line_widths.max
-      end
-
-      # Compute the rendered width of a string, taking fallback fonts into account
-      def rendered_width_of_string str, opts = {}
-        opts = opts.merge kerning: default_kerning?
-        if str.length == 1
-          rendered_width_of_char str, opts
-        elsif (chars = str.each_char).all? {|char| font.glyph_present? char }
-          width_of_string str, opts
+      # Lookup margin for theme element and side, then delegate to margin method.
+      # If margin value is not found, assume 0.
+      def theme_margin category, side, node = true
+        if node
+          category = :block if node != true && node.context == :section
+          margin (@theme[%(#{category}_margin_#{side})] || 0), side
         else
-          char_widths = chars.map {|char| rendered_width_of_char char, opts }
-          char_widths.sum + (char_widths.length * character_spacing)
-        end
-      end
-
-      # Compute the rendered width of a char, taking fallback fonts into account
-      def rendered_width_of_char char, opts = {}
-        unless @fallback_fonts.empty? || (font.glyph_present? char)
-          @fallback_fonts.each do |fallback_font|
-            font fallback_font do
-              return width_of_string char, opts if font.glyph_present? char
-            end
-          end
+          0
         end
-        width_of_string char, opts
       end
 
       # TODO: document me, esp the first line formatting functionality
@@ -4286,7 +4362,7 @@ module Asciidoctor
         opts = { leading: line_metrics.leading, final_gap: line_metrics.final_gap }.merge opts
         string = string.gsub CjkLineBreakRx, ZeroWidthSpace if @cjk_line_breaks
         return text_box string, opts if opts[:height]
-        move_down line_metrics.padding_top
+        opts[:initial_gap] = line_metrics.padding_top
         if (hanging_indent = (opts.delete :hanging_indent) || 0) > 0
           indent hanging_indent do
             text string, (opts.merge indent_paragraphs: -hanging_indent)
@@ -4302,8 +4378,7 @@ module Asciidoctor
 
       # QUESTION: combine with typeset_text?
       def typeset_formatted_text fragments, line_metrics, opts = {}
-        move_down line_metrics.padding_top
-        opts = { leading: line_metrics.leading, final_gap: line_metrics.final_gap }.merge opts
+        opts = { leading: line_metrics.leading, initial_gap: line_metrics.padding_top, final_gap: line_metrics.final_gap }.merge opts
         if (hanging_indent = (opts.delete :hanging_indent) || 0) > 0
           indent hanging_indent do
             formatted_text fragments, (opts.merge indent_paragraphs: -hanging_indent)
@@ -4314,94 +4389,67 @@ module Asciidoctor
         move_down line_metrics.padding_bottom
       end
 
-      def height_of_typeset_text string, opts = {}
-        line_metrics = (calc_line_metrics opts[:line_height] || @base_line_height)
-        (height_of string, leading: line_metrics.leading, final_gap: line_metrics.final_gap) + line_metrics.padding_top + (opts[:single_line] ? 0 : line_metrics.padding_bottom)
-      end
-
-      # NOTE: only used when tabsize attribute is not specified
-      # tabs must always be replaced with spaces in order for the indentation guards to work
-      def expand_tabs string
-        if string.nil_or_empty?
-          ''
-        elsif string.include? TAB
-          full_tab_space = ' ' * (tab_size = 4)
-          (string.split LF, -1).map do |line|
-            if line.empty? || !(tab_idx = line.index TAB)
-              line
-            else
-              if tab_idx == 0
-                leading_tabs = 0
-                line.each_byte do |b|
-                  break unless b == 9
-                  leading_tabs += 1
-                end
-                line = %(#{full_tab_space * leading_tabs}#{rest = line.slice leading_tabs, line.length})
-                next line unless rest.include? TAB
-              end
-              # keeps track of how many spaces were added to adjust offset in match data
-              spaces_added = 0
-              idx = 0
-              result = ''
-              line.each_char do |c|
-                if c == TAB
-                  # calculate how many spaces this tab represents, then replace tab with spaces
-                  if (offset = idx + spaces_added) % tab_size == 0
-                    spaces_added += (tab_size - 1)
-                    result += full_tab_space
-                  else
-                    unless (spaces = tab_size - offset % tab_size) == 1
-                      spaces_added += (spaces - 1)
-                    end
-                    result += (' ' * spaces)
-                  end
-                else
-                  result += c
-                end
-                idx += 1
-              end
-              result
-            end
-          end.join LF
+      def write pdf_doc, target
+        if target.respond_to? :write
+          target = ::QuantifiableStdout.new $stdout if target == $stdout
+          pdf_doc.render target
         else
-          string
+          pdf_doc.render_file target
+          # QUESTION: restore attributes first?
+          @pdfmark&.generate_file target
+          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']
+          remove_tmp_files
+        elsif to_file
+          scratch_target = (target.slice 0, target.length - (target_ext = ::File.extname target).length) + '-scratch' + target_ext
+          scratch.render_file scratch_target
         end
+        clear_scratch
+        nil
       end
 
-      # Add an indentation guard at the start of indented lines.
-      # Expand tabs to spaces if tabs are present
-      def guard_indentation string
-        unless (string = expand_tabs string).empty?
-          string[0] = GuardedIndent if string.start_with? ' '
-          string.gsub! InnerIndent, GuardedInnerIndent if string.include? InnerIndent
+      # 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_sym
+        if (method_name = method_sym.to_s).start_with? 'layout_'
+          alias_method %(ink_#{method_name.slice 7, method_name.length}).to_sym, method_sym
+        elsif method_name == 'convert_listing_or_literal' || method_name == 'convert_code'
+          alias_method :convert_listing, method_sym
+          alias_method :convert_literal, method_sym
         end
-        string
       end
 
-      def guard_indentation_in_fragments fragments
-        start_of_line = true
-        fragments.each do |fragment|
-          next if (text = fragment[:text]).empty?
-          if start_of_line && (text.start_with? ' ')
-            fragment[:text] = GuardedIndent + (((text = text.slice 1, text.length).include? InnerIndent) ? (text.gsub InnerIndent, GuardedInnerIndent) : text)
-          elsif text.include? InnerIndent
-            fragment[:text] = text.gsub InnerIndent, GuardedInnerIndent
-          end
-          start_of_line = text.end_with? LF
-        end
-        fragments
+      # 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
 
-      # Derive a PDF-safe, ASCII-only anchor name from the given value.
-      # Encodes value into hex if it contains characters outside the ASCII range.
-      # If value is nil, derive an anchor name from the default_value, if given.
-      def derive_anchor_from_id value, default_value = nil
-        if value
-          value.ascii_only? ? value : %(0x#{::PDF::Core.string_to_hex value})
-        else
-          %(__anchor-#{default_value})
-        end
-      end
+      private
 
       def add_dest_for_top doc
         unless (top_page = doc.attr 'pdf-page-start') > page_count
@@ -4414,302 +4462,359 @@ module Asciidoctor
         nil
       end
 
-      # If an id is provided or the node passed as the first argument has an id,
-      # add a named destination to the document equivalent to the node id at the
-      # current y position. If the node does not have an id and an id is not
-      # specified, do nothing.
-      #
-      # If the node is a section, and the current y position is the top of the
-      # page, set the y position equal to the page height to improve the navigation
-      # experience. If the current x position is at or inside the left margin, set
-      # the x position equal to 0 (left edge of page) to improve the navigation
-      # experience.
-      def add_dest_for_block node, id: nil, y: nil
-        if !scratch? && (id ||= node.id)
-          dest_x = bounds.absolute_left.truncate 4
-          # QUESTION: when content is aligned to left margin, should we keep precise x value or just use 0?
-          dest_x = 0 if dest_x <= page_margin_left
-          unless (dest_y = y)
-            dest_y = @y
-            dest_y += [page_height - dest_y, -@theme.block_anchor_top.to_f].min
+      def add_link_to_image uri, image_info, image_opts
+        image_width = image_info[:width]
+        image_height = image_info[:height]
+
+        case image_opts[:position]
+        when :center
+          image_x = bounds.left_side + (bounds.width - image_width) * 0.5
+        when :right
+          image_x = bounds.right_side - image_width
+        else # :left, nil
+          image_x = bounds.left_side
+        end
+
+        case image_opts[:vposition]
+        when :top
+          image_y = bounds.absolute_top
+        when :center
+          image_y = bounds.absolute_top - (bounds.height - image_height) * 0.5
+        when :bottom
+          image_y = bounds.absolute_bottom + image_height
+        else
+          image_y = y - image_opts[:vposition]
+        end unless (image_y = image_opts[:y])
+
+        link_annotation [image_x, (image_y - image_height), (image_x + image_width), image_y], Border: [0, 0, 0], A: { Type: :Action, S: :URI, URI: uri.as_pdf }
+      end
+
+      def admonition_icon_data key
+        if (icon_data = @theme[%(admonition_icon_#{key})])
+          icon_data = (AdmonitionIcons[key] || {}).merge icon_data
+          if (icon_name = icon_data[:name])
+            unless icon_name.start_with?(*IconSetPrefixes)
+              log(:info) { %(#{key} admonition in theme uses icon from deprecated fa icon set; use fas, far, or fab instead) }
+              icon_data[:name] = %(fa-#{icon_name}) unless icon_name.start_with? 'fa-'
+            end
+          else
+            icon_data[:name] = AdmonitionIcons[:note][:name]
           end
-          # TODO: find a way to store only the ref of the destination; look it up when we need it
-          node.set_attr 'pdf-destination', (node_dest = (dest_xyz dest_x, dest_y))
-          add_dest id, node_dest
+        else
+          (icon_data = AdmonitionIcons[key] || {})[:name] ||= AdmonitionIcons[:note][:name]
         end
-        nil
+        icon_data
       end
 
-      def resolve_doctitle doc, partition = nil
-        if doc.header?
-          doc.doctitle partition: partition
-        elsif partition
-          ::Asciidoctor::Document::Title.new (doc.attr 'untitled-label'), separator: (doc.attr 'title-separator')
+      def allocate_space_for_list_item line_metrics
+        advance_page if !at_page_top? && cursor < line_metrics.height + line_metrics.leading + line_metrics.padding_top
+      end
+
+      def apply_text_decoration styles, category, level = nil
+        if (text_decoration_style = TextDecorationStyleTable[level && @theme[%(#{category}_h#{level}_text_decoration)] || @theme[%(#{category}_text_decoration)]])
+          {
+            styles: (styles << text_decoration_style),
+            text_decoration_color: level && @theme[%(#{category}_h#{level}_text_decoration_color)] || @theme[%(#{category}_text_decoration_color)],
+            text_decoration_width: level && @theme[%(#{category}_h#{level}_text_decoration_width)] || @theme[%(#{category}_text_decoration_width)],
+          }.compact
         else
-          doc.attr 'untitled-label'
+          styles.empty? ? {} : { styles: styles }
         end
       end
 
-      def resolve_text_align_from_role roles, query_theme: false, remove_predefined: false
-        if (align_role = roles.reverse.find {|r| TextAlignmentRoles.include? r })
-          roles.replace roles - TextAlignmentRoles if remove_predefined
-          (align_role.slice 5, align_role.length).to_sym
-        elsif query_theme
-          roles.reverse.each do |role|
-            if (align = @theme[%(role_#{role}_text_align)])
-              return align.to_sym
+      # Arrange fragments by line in an arranger and return an unfinalized arranger.
+      #
+      # Finalizing the arranger is deferred since it must be done in the context of
+      # the global font settings you want applied to each fragment.
+      def arrange_fragments_by_line fragments, _opts = {}
+        arranger = ::Prawn::Text::Formatted::Arranger.new self
+        by_line = arranger.consumed = []
+        fragments.each do |fragment|
+          if (text = fragment[:text]) == LF || !(text.include? LF)
+            by_line << fragment
+          else
+            text.scan LineScanRx do |line|
+              by_line << (line == LF ? { text: LF } : (fragment.merge text: line))
             end
           end
-          nil
         end
+        arranger
       end
 
-      # Deprecated
-      alias resolve_alignment_from_role resolve_text_align_from_role
+      # NOTE: assume URL is escaped (i.e., contains character references such as &amp;)
+      def breakable_uri uri
+        scheme, address = uri.split UriSchemeBoundaryRx, 2
+        address, scheme = scheme, address unless address
+        unless address.nil_or_empty?
+          address = address.gsub UriBreakCharsRx, UriBreakCharRepl
+          # NOTE: require at least two characters after a break
+          address.slice!(-2) if address[-2] == ZeroWidthSpace
+        end
+        %(#{scheme}#{address})
+      end
 
-      # QUESTION: is this method still necessary?
-      def resolve_imagesdir doc
-        if (imagesdir = doc.attr 'imagesdir').nil_or_empty? || (imagesdir = imagesdir.chomp '/') == '.'
-          nil
+      # Calculate the font size (down to the minimum font size) that would allow
+      # all the specified fragments to fit in the available width without wrapping lines.
+      #
+      # Return the calculated font size if an adjustment is necessary or nil if no
+      # font size adjustment is necessary.
+      def compute_autofit_font_size fragments, category
+        arranger = arrange_fragments_by_line fragments
+        # NOTE: finalizing the line here generates fragments & calculates their widths using the current font settings
+        # NOTE: it also removes zero-width spaces
+        arranger.finalize_line
+        actual_width = width_of_fragments arranger.fragments
+        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
+            min
+          else
+            adjusted_font_size
+          end
+        end
+      end
+
+      def consolidate_ranges nums
+        if nums.size > 1
+          prev = nil
+          nums.each_with_object [] do |num, accum|
+            if prev && (prev.to_i + 1) == num.to_i
+              accum[-1][1] = num
+            else
+              accum << [num]
+            end
+            prev = num
+          end.map {|range| range.join '-' }
         else
-          imagesdir
+          nums
         end
       end
 
-      # Resolve the system path of the specified image path.
-      #
-      # Resolve and normalize the absolute system path of the specified image,
-      # taking into account the imagesdir attribute. If an image path is not
-      # specified, the path is read from the target attribute of the specified
-      # document node.
-      #
-      # If the target is a URI and the allow-uri-read attribute is set on the
-      # document, read the file contents to a temporary file and return the path to
-      # the temporary file. If the target is a URI and the allow-uri-read attribute
-      # is not set, or the URI cannot be read, this method returns a nil value.
-      #
-      # When a temporary file is used, the file is stored in @tmp_files to be cleaned up after conversion.
-      def resolve_image_path node, image_path, image_format, relative_to = true
-        doc = node.document
-        imagesdir = relative_to == true ? (resolve_imagesdir doc) : relative_to
-        # NOTE: base64 logic currently used for inline images
-        if ::Base64 === image_path
-          return @tmp_files[image_path] if @tmp_files.key? image_path
-          tmp_image = ::Tempfile.create %W(image- .#{image_format})
-          tmp_image.binmode unless image_format == 'svg'
-          tmp_image.write ::Base64.decode64 image_path
-          tmp_image.close
-          @tmp_files[image_path] = tmp_image.path
-        # NOTE: this will catch a classloader resource path on JRuby (e.g., uri:classloader:/path/to/image)
-        elsif ::File.absolute_path? image_path
-          ::File.absolute_path image_path
-        elsif !(is_uri = node.is_uri? image_path) && imagesdir && (::File.absolute_path? imagesdir)
-          ::File.absolute_path image_path, imagesdir
-        # handle case when image is a URI
-        elsif is_uri || (imagesdir && (node.is_uri? imagesdir) && (image_path = node.normalize_web_path image_path, imagesdir, false))
-          if !allow_uri_read
-            log :warn, %(cannot embed remote image: #{image_path} (allow-uri-read attribute not enabled))
-            return
-          elsif @tmp_files.key? image_path
-            return @tmp_files[image_path]
+      def conum_glyph number
+        @conum_glyphs[number - 1]
+      end
+
+      # Derive a PDF-safe, ASCII-only anchor name from the given value.
+      # Encodes value into hex if it contains characters outside the ASCII range.
+      # If value is nil, derive an anchor name from the default_value, if given.
+      def derive_anchor_from_id value, default_value = nil
+        if value
+          value.ascii_only? ? value : %(0x#{::PDF::Core.string_to_hex value})
+        else
+          %(__anchor-#{default_value})
+        end
+      end
+
+      def draw_image_border top, w, h, alignment
+        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
+            bb_x = (bounds.width - w) * 0.5
+          elsif alignment == :right
+            bb_x = bounds.width - w
           end
-          tmp_image = ::Tempfile.create ['image-', image_format && %(.#{image_format})]
-          tmp_image.binmode if (binary = image_format != 'svg')
-          begin
-            load_open_uri.open_uri(image_path, (binary ? 'rb' : 'r')) {|fd| tmp_image.write fd.read }
-            tmp_image.close
-            @tmp_files[image_path] = tmp_image.path
-          rescue
-            @tmp_files[image_path] = nil
-            log :warn, %(could not retrieve remote image: #{image_path}; #{$!.message})
-            tmp_image.close
-            unlink_tmp_file tmp_image.path
-            nil
+          bounding_box [(bb_x || 0), top], width: (bb_width || w), height: h, position: alignment do
+            theme_fill_and_stroke_bounds :image
           end
-        # handle case when image is a local file
-        else
-          node.normalize_system_path image_path, imagesdir, nil, target_name: 'image'
+          true
         end
       end
 
-      def resolve_icon_image_path node, type, resolve = true
-        if (data_uri_enabled = (doc = node.document).attr? 'data-uri')
-          doc.remove_attr 'data-uri'
+      # Reduce icon height to fit inside bounds.height. Icons will not render
+      # properly if they are larger than the current bounds.height.
+      def fit_icon_to_bounds preferred_size
+        (max_height = bounds.height) < preferred_size ? max_height : preferred_size
+      end
+
+      def font_path font_file, fonts_dir
+        # resolve relative to built-in font dir unless path is absolute
+        ::File.absolute_path font_file, fonts_dir
+      end
+
+      def generate_manname_section node
+        title = node.attr 'manname-title', 'Name'
+        if (next_section_title = node.sections[0]&.title) && next_section_title.upcase == next_section_title
+          title = title.upcase
         end
+        sect = Section.new node, 1
+        sect.sectname = 'section'
+        sect.id = node.attr 'manname-id'
+        sect.title = title
+        sect << (Block.new sect, :paragraph, source: %(#{node.attr 'manname'} - #{node.attr 'manpurpose'}), subs: :normal)
+        sect
+      end
+
+      def get_char code
+        (code.start_with? '\u') ? ([((code.slice 2, code.length).to_i 16)].pack 'U1') : code
+      end
+
+      def get_icon_image_path node, type, resolve = true
+        doc = node.document
+        doc.remove_attr 'data-uri' if (data_uri_enabled = doc.attr? 'data-uri')
         # NOTE: icon_uri will consider icon attribute on node first, then type
         icon_path, icon_format = ::Asciidoctor::Image.target_and_format node.icon_uri type
         doc.set_attr 'data-uri', '' if data_uri_enabled
         resolve ? (resolve_image_path node, icon_path, icon_format, nil) : icon_path
       end
 
-      # Resolve the path and sizing of the background image either from a document attribute or theme key.
-      #
-      # Returns the argument list for the image method if the document attribute or theme key is found. Otherwise,
-      # nothing. The first argument in the argument list is the image path. If that value is nil, the background
-      # image is disabled. The second argument is the options hash to specify the dimensions, such as width and fit.
-      def resolve_background_image doc, theme, key, opts = {}
-        if ::String === key
-          theme_key = opts.delete :theme_key
-          image_path = (doc.attr key) || (from_theme = theme[theme_key || (key.tr '-', '_').to_sym])
-        else
-          image_path = from_theme = theme[key]
+      def init_float_box _node, block_width, block_height, float_to
+        gap = ::Array === (gap = @theme.image_float_gap) ? gap.dup : [gap, gap]
+        float_w = block_width + (gap[0] ||= 12)
+        float_h = block_height + (gap[1] ||= 6)
+        box_l = bounds.left + (float_to == 'right' ? 0 : float_w)
+        box_t = cursor + block_height
+        box_w = bounds.width - float_w
+        box_r = box_l + box_w
+        box_h = [box_t, float_h].min
+        box_b = box_t - box_h
+        move_cursor_to box_t
+        @float_box = { page: page_number, top: box_t, right: box_r, bottom: box_b, left: box_l, width: box_w, height: box_h, gap: gap }
+      end
+
+      # NOTE: init_page is called within a float context; this will suppress prawn-svg messing with the cursor
+      # NOTE: init_page is not called for imported pages, front and back cover pages, and other image pages
+      def init_page *_args
+        next_page_side = page_side nil, @folio_placement[:inverted]
+        if @media == 'prepress' && (next_page_margin = @page_margin_by_side[page_number == 1 ? :cover : next_page_side]) != page_margin
+          set_page_margin next_page_margin
         end
-        symbolic_paths = opts.delete :symbolic_paths
-        if image_path
-          if symbolic_paths&.include? image_path
-            return [image_path, {}]
-          elsif image_path == 'none'
-            return []
-          elsif (image_path.include? ':') && image_path =~ ImageAttributeValueRx
-            image_attrs = (AttributeList.new $2).parse %w(alt width)
-            if from_theme
-              image_path = apply_subs_discretely doc, $1, subs: [:attributes]
-              image_relative_to = @themesdir
+        unless @page_bg_color == 'FFFFFF'
+          tare = true
+          fill_absolute_bounds @page_bg_color
+        end
+        if (bg_image_path, bg_image_opts = @page_bg_image[next_page_side])
+          tare = true
+          begin
+            if bg_image_opts[:format] == 'pdf'
+              # NOTE: pages that use PDF for the background do not support a background color or running content
+              # IMPORTANT: the background PDF must have the same dimensions as the current PDF
+              import_page bg_image_path, (bg_image_opts.merge replace: true, advance: false, advance_if_missing: false)
             else
-              image_path = $1
-              image_relative_to = true
+              canvas { image bg_image_path, ({ position: :center, vposition: :center }.merge bg_image_opts) }
             end
-          elsif from_theme
-            image_path = apply_subs_discretely doc, image_path, subs: [:attributes]
-            image_relative_to = @themesdir
+          rescue
+            facing_page_side = (PageSides - [next_page_side])[0]
+            @page_bg_image[facing_page_side] = nil if @page_bg_image[facing_page_side] == @page_bg_image[next_page_side]
+            @page_bg_image[next_page_side] = nil
+            log :warn, %(could not embed page background image: #{bg_image_path}; #{$!.message})
           end
+        end
+        page.tare_content_stream if tare
+      end
 
-          image_path, image_format = ::Asciidoctor::Image.target_and_format image_path, image_attrs
-          image_path = resolve_image_path doc, image_path, image_format, image_relative_to
-
-          return unless image_path
-
-          unless ::File.readable? image_path
-            log :warn, %(#{key.to_s.tr '-_', ' '} not found or readable: #{image_path})
-            return
+      def ink_paragraph_in_float_box node, float_box, prose_opts, role_keys, block_next, insert_margin_bottom
+        @float_box = para_font_descender = para_font_size = end_cursor = nil
+        if role_keys
+          line_metrics = theme_font_cascade role_keys do
+            para_font_descender = font.descender
+            para_font_size = font_size
+            calc_line_metrics @base_line_height
           end
-
-          if image_format == 'pdf'
-            [image_path, page: [((image_attrs || {})['page']).to_i, 1].max, format: image_format]
+        else
+          para_font_descender = font.descender
+          para_font_size = font_size
+          line_metrics = calc_line_metrics @base_line_height
+        end
+        # allocate the space of at least one empty line below block
+        line_height_length = line_metrics.height + line_metrics.leading + line_metrics.padding_top
+        start_page_number = float_box[:page]
+        start_cursor = cursor
+        block_bottom = (float_box_bottom = float_box[:bottom]) + float_box[:gap][1]
+        # use :at to incorporate padding top from line metrics since text_box method does not apply it
+        # use :final_gap to incorporate padding bottom from line metrics
+        # use :draw_text_callback to track end cursor (requires applying :final_gap to result manually)
+        prose_opts.update \
+          at: [float_box[:left], start_cursor - line_metrics.padding_top],
+          width: float_box[:width],
+          height: [cursor, float_box[:height] - (float_box[:top] - start_cursor) + line_height_length].min,
+          final_gap: para_font_descender + line_metrics.padding_bottom,
+          draw_text_callback: (proc do |text, opts|
+            draw_text! text, opts
+            end_cursor = opts[:at][1] # does not include :final_gap value
+          end)
+        overflow_text = role_keys ?
+          theme_font_cascade(role_keys) { ink_prose node.content, prose_opts } :
+          (ink_prose node.content, prose_opts)
+        move_cursor_to end_cursor -= prose_opts[:final_gap] if end_cursor # ink_prose with :height does not move cursor
+        if overflow_text.empty?
+          if block_next && (supports_float_wrapping? block_next)
+            insert_margin_bottom.call
+            @float_box = float_box if page_number == start_page_number && cursor > start_cursor - prose_opts[:height]
+          elsif end_cursor > block_bottom
+            move_cursor_to block_bottom
+            theme_margin :block, :bottom, block_next
           else
-            [image_path, (resolve_image_options image_path, image_format, image_attrs, (({ background: true, container_size: [page_width, page_height] }.merge opts)))]
+            insert_margin_bottom.call
+          end
+        else
+          overflow_prose_opts = { align: prose_opts[:align] || @base_text_align.to_sym }
+          unless end_cursor
+            overflow_prose_opts[:indent_paragraphs] = prose_opts[:indent_paragraphs]
+            move_cursor_to float_box_bottom if start_cursor > float_box_bottom
           end
+          role_keys ?
+            theme_font_cascade(role_keys) { typeset_formatted_text overflow_text, line_metrics, overflow_prose_opts } :
+            (typeset_formatted_text overflow_text, line_metrics, overflow_prose_opts)
+          insert_margin_bottom.call
         end
       end
 
-      def resolve_image_options image_path, image_format, image_attrs, opts = {}
-        if image_format == 'svg'
-          image_opts = {
-            enable_file_requests_with_root: (::File.dirname image_path),
-            enable_web_requests: allow_uri_read ? (method :load_open_uri).to_proc : false,
-            cache_images: cache_uri,
-            fallback_font_name: fallback_svg_font_name,
-            format: 'svg',
-          }
+      def insert_toc_section doc, toc_title, toc_page_nums
+        if (doc.attr? 'toc-placement', 'macro') && (toc_node = (doc.find_by context: :toc)[0])
+          if (parent_section = toc_node.parent).context == :section
+            grandparent_section = parent_section.parent
+            toc_level = parent_section.level
+            insert_idx = (grandparent_section.blocks.index parent_section) + 1
+          else
+            grandparent_section = doc
+            toc_level = doc.sections[0].level
+            insert_idx = 0
+          end
+          toc_dest = toc_node.attr 'pdf-destination'
         else
-          image_opts = {}
+          grandparent_section = doc
+          toc_level = doc.sections[0].level
+          insert_idx = 0
+          toc_dest = dest_top toc_page_nums.first
         end
-        container_size = opts[:container_size]
-        if image_attrs
-          if (alt = image_attrs['alt'])
-            image_opts[:alt] = %([#{alt}])
-          end
-          if (background = opts[:background]) && (image_pos = image_attrs['position']) && (image_pos = resolve_background_position image_pos, nil)
-            image_opts.update image_pos
-          end
-          if (image_fit = image_attrs['fit'] || (background ? 'contain' : nil))
-            image_fit = 'contain' if image_format == 'svg' && image_fit == 'fill'
-            container_width, container_height = container_size
-            case image_fit
-            when 'none'
-              if (image_width = resolve_explicit_width image_attrs, bounds_width: container_width)
-                image_opts[:width] = image_width
-              end
-            when 'scale-down'
-              # NOTE: if width and height aren't set in SVG, real width and height are computed after stretching viewbox to fit page
-              if (image_width = resolve_explicit_width image_attrs, bounds_width: container_width)
-                if image_width > container_width
-                  image_opts[:fit] = container_size
-                else
-                  image_size = intrinsic_image_dimensions image_path, image_format
-                  if image_width * (image_size[:height].to_f / image_size[:width]) > container_height
-                    image_opts[:fit] = container_size
-                  else
-                    image_opts[:width] = image_width
-                  end
-                end
-              else
-                image_size = intrinsic_image_dimensions image_path, image_format
-                image_opts[:fit] = container_size if image_size[:width] > container_width || image_size[:height] > container_height
-              end
-            when 'cover'
-              # QUESTION: should we take explicit width into account?
-              image_size = intrinsic_image_dimensions image_path, image_format
-              if container_width * (image_size[:height].to_f / image_size[:width]) < container_height
-                image_opts[:height] = container_height
-              else
-                image_opts[:width] = container_width
-              end
-            when 'fill'
-              image_opts[:width] = container_width
-              image_opts[:height] = container_height
-            else # 'contain'
-              image_opts[:fit] = container_size
-            end
-          elsif (image_width = resolve_explicit_width image_attrs, bounds_width: container_size[0])
-            image_opts[:width] = image_width
-          else # default to fit=contain if sizing is not specified
-            image_opts[:fit] = container_size
-          end
+        toc_section = Section.new grandparent_section, toc_level, false, attributes: { 'pdf-destination' => toc_dest }
+        toc_section.title = toc_title
+        grandparent_section.blocks.insert insert_idx, toc_section
+        toc_section
+      end
+
+      def load_open_uri
+        if @cache_uri && !(defined? ::OpenURI::Cache) && (Helpers.require_library 'open-uri/cached', 'open-uri-cached', :warn).nil?
+          # disable URI caching if library fails to load
+          @cache_uri = false
+        end
+        ::OpenURI
+      end
+
+      def on_image_error _reason, node, target, opts
+        log :warn, opts[:message] if opts.key? :message
+        alt_text_vars = { alt: (node.attr 'alt'), target: target }
+        alt_text_template = @theme.image_alt_content || '%{link}[%{alt}]%{/link} | <em>%{target}</em>' # rubocop:disable Style/FormatStringToken
+        return if alt_text_template.empty?
+        if (link = node.attr 'link')
+          alt_text_vars[:link] = %(<a href="#{link}">)
+          alt_text_vars[:'/link'] = '</a>'
         else
-          image_opts[:fit] = container_size
+          alt_text_vars[:link] = ''
+          alt_text_vars[:'/link'] = ''
         end
-        image_opts
+        theme_font :image_alt do
+          ink_prose alt_text_template % alt_text_vars, align: opts[:align], margin: 0, normalize: false, single_line: true
+        end
+        ink_caption node, category: :image, end: :bottom if node.title?
+        theme_margin :block, :bottom, (next_enclosed_block node) unless opts[:pinned]
+        nil
       end
 
-      # Resolves the explicit width, if specified, as a PDF pt value.
-      #
-      # Resolves the explicit width, first considering the pdfwidth attribute, then the scaledwidth
-      # attribute, then the theme default (if enabled by the :use_fallback option), and finally the
-      # width attribute. If the specified value is in pixels, the value is scaled by 75% to perform
-      # approximate CSS px to PDF pt conversion. If the value is a percentage, and the
-      # bounds_width option is given, the percentage of the bounds_width value is returned.
-      # Otherwise, the percentage width is returned.
-      #--
-      # QUESTION: should we enforce positive result?
-      def resolve_explicit_width attrs, opts = {}
-        bounds_width = opts[:bounds_width]
-        # QUESTION: should we restrict width to bounds_width for pdfwidth?
-        if attrs.key? 'pdfwidth'
-          if (width = attrs['pdfwidth']).end_with? '%'
-            bounds_width ? (width.to_f / 100) * bounds_width : width
-          elsif opts[:support_vw] && (width.end_with? 'vw')
-            (width.chomp 'vw').extend ViewportWidth
-          else
-            str_to_pt width
-          end
-        elsif attrs.key? 'scaledwidth'
-          # NOTE: the parser automatically appends % if value is unitless
-          if (width = attrs['scaledwidth']).end_with? '%'
-            bounds_width ? (width.to_f / 100) * bounds_width : width
-          else
-            str_to_pt width
-          end
-        elsif opts[:use_fallback] && (width = @theme.image_width)
-          if ::Numeric === width
-            width
-          elsif (width = width.to_s).end_with? '%'
-            bounds_width ? (width.to_f / 100) * bounds_width : bounds_width
-          elsif opts[:support_vw] && (width.end_with? 'vw')
-            (width.chomp 'vw').extend ViewportWidth
-          else
-            str_to_pt width
-          end
-        elsif attrs.key? 'width'
-          if (width = attrs['width']).end_with? '%'
-            width = (width.to_f / 100) * bounds_width if bounds_width
-          elsif DigitsRx.match? width
-            width = to_pt width.to_f, :px
-          else
-            return
-          end
-          bounds_width && opts[:constrain_to_bounds] ? [bounds_width, width].min : width
-        end
+      def remove_tmp_files
+        @tmp_files.reject! {|_, path| path ? (unlink_tmp_file path) : true }
       end
 
       def resolve_background_position value, default_value = {}
@@ -4744,128 +4849,50 @@ module Asciidoctor
         end
       end
 
-      def resolve_top val
-        if val.end_with? 'vh'
-          page_height * (1 - (val.to_f / 100))
-        elsif val.end_with? '%'
-          @y - effective_page_height * (val.to_f / 100)
-        else
-          @y - (str_to_pt val)
-        end
+      def resolve_font_kerning keyword
+        FontKerningTable[keyword]
       end
 
-      def apply_subs_discretely doc, value, opts = {}
-        if (imagesdir = opts[:imagesdir])
-          imagesdir_to_restore = doc.attr 'imagesdir'
-          doc.set_attr 'imagesdir', imagesdir
-        end
-        # FIXME: get sub_attributes to handle drop-line w/o a warning
-        doc.set_attr 'attribute-missing', 'skip' unless (attribute_missing = doc.attr 'attribute-missing') == 'skip'
-        value = value.gsub '\{', '\\\\\\{' if (escaped_attr_ref = value.include? '\{')
-        value = (subs = opts[:subs]) ? (doc.apply_subs value, subs) : (doc.apply_subs value)
-        value = (value.split LF).delete_if {|line| SimpleAttributeRefRx.match? line }.join LF if opts[:drop_lines_with_unresolved_attributes] && (value.include? '{')
-        value = value.gsub '\{', '{' if escaped_attr_ref
-        doc.set_attr 'attribute-missing', attribute_missing unless attribute_missing == 'skip'
-        if imagesdir
-          if imagesdir_to_restore
-            doc.set_attr 'imagesdir', imagesdir_to_restore
+      def resolve_pagenums val
+        pgnums = []
+        ((val.include? ',') ? (val.split ',') : (val.split ';')).each do |entry|
+          if entry.include? '..'
+            from, _, to = entry.partition '..'
+            pgnums += ([from.to_i, 1].max..[to.to_i, 1].max).to_a
           else
-            doc.remove_attr 'imagesdir'
+            pgnums << entry.to_i
           end
         end
-        value
+
+        pgnums
       end
 
-      def next_enclosed_block block, descend: false
-        return if (context = block.context) == :document
-        parent_context = (parent = block.parent).context
-        if (list_item = context == :list_item)
-          return block.blocks[0] if descend && block.blocks?
-          siblings = parent.items
+      def resolve_top val
+        if val.end_with? 'vh'
+          page_height * (1 - (val.to_f / 100))
+        elsif val.end_with? '%'
+          @y - effective_page_height * (val.to_f / 100)
         else
-          siblings = parent.blocks
-        end
-        siblings = siblings.flatten if parent_context == :dlist
-        if block != siblings[-1]
-          (self_idx = siblings.index block) && siblings[self_idx + 1]
-        elsif parent_context == :list_item || (parent_context == :open && parent.style != 'abstract') || parent_context == :section
-          next_enclosed_block parent
-        elsif list_item && (grandparent = parent.parent).context == :list_item
-          next_enclosed_block grandparent
+          @y - (str_to_pt val)
         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_sym
-        if (method_name = method_sym.to_s).start_with? 'layout_'
-          alias_method %(ink_#{method_name.slice 7, method_name.length}).to_sym, method_sym
-        elsif method_name == 'convert_listing_or_literal' || method_name == 'convert_code'
-          alias_method :convert_listing, method_sym
-          alias_method :convert_literal, method_sym
+      def resolve_text_transform key, use_fallback = true
+        if (transform = ::Hash === key ? (key.delete :text_transform) : @theme[key])
+          transform == 'none' ? nil : transform
+        elsif use_fallback
+          @text_transform
         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
-        image_width = image_info[:width]
-        image_height = image_info[:height]
-
-        case image_opts[:position]
-        when :center
-          image_x = bounds.left_side + (bounds.width - image_width) * 0.5
-        when :right
-          image_x = bounds.right_side - image_width
-        else # :left, nil
-          image_x = bounds.left_side
-        end
-
-        case image_opts[:vposition]
-        when :top
-          image_y = bounds.absolute_top
-        when :center
-          image_y = bounds.absolute_top - (bounds.height - image_height) * 0.5
-        when :bottom
-          image_y = bounds.absolute_bottom + image_height
+      # 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, transparent_color = fallback_color
+        if (color = @theme[key])
+          color == 'transparent' ? transparent_color : color
         else
-          image_y = y - image_opts[:vposition]
-        end unless (image_y = image_opts[:y])
-
-        link_annotation [image_x, (image_y - image_height), (image_x + image_width), image_y], Border: [0, 0, 0], A: { Type: :Action, S: :URI, URI: uri.as_pdf }
-      end
-
-      def load_open_uri
-        if @cache_uri && !(defined? ::OpenURI::Cache) && (Helpers.require_library 'open-uri/cached', 'open-uri-cached', :warn).nil?
-          # disable URI caching if library fails to load
-          @cache_uri = false
+          fallback_color
         end
-        ::OpenURI
-      end
-
-      def remove_tmp_files
-        @tmp_files.reject! {|_, path| path ? (unlink_tmp_file path) : true }
       end
 
       def unlink_tmp_file path
@@ -4876,6 +4903,23 @@ module Asciidoctor
         false
       end
 
+      # Calculate the width that is needed to print all the
+      # fragments without wrapping any lines.
+      #
+      # This method assumes endlines are represented as discrete entries in the
+      # fragments array.
+      def width_of_fragments fragments
+        line_widths = [0]
+        fragments.each do |fragment|
+          if fragment.text == LF
+            line_widths << 0
+          else
+            line_widths[-1] += fragment.width
+          end
+        end
+        line_widths.max
+      end
+
       # Promotes author to primary author attributes around block; restores original attributes after block executes
       def with_author doc, author, primary
         doc.remove_attr 'url' if (original_url = doc.attr 'url')
@@ -4908,53 +4952,7 @@ module Asciidoctor
         result
       end
 
-      # NOTE: assume URL is escaped (i.e., contains character references such as &amp;)
-      def breakable_uri uri
-        scheme, address = uri.split UriSchemeBoundaryRx, 2
-        address, scheme = scheme, address unless address
-        unless address.nil_or_empty?
-          address = address.gsub UriBreakCharsRx, UriBreakCharRepl
-          # NOTE: require at least two characters after a break
-          address.slice!(-2) if address[-2] == ZeroWidthSpace
-        end
-        %(#{scheme}#{address})
-      end
-
-      def consolidate_ranges nums
-        if nums.size > 1
-          prev = nil
-          nums.each_with_object [] do |num, accum|
-            if prev && (prev.to_i + 1) == num.to_i
-              accum[-1][1] = num
-            else
-              accum << [num]
-            end
-            prev = num
-          end.map {|range| range.join '-' }
-        else
-          nums
-        end
-      end
-
-      def resolve_pagenums val
-        pgnums = []
-        ((val.include? ',') ? (val.split ',') : (val.split ';')).each do |entry|
-          if entry.include? '..'
-            from, _, to = entry.partition '..'
-            pgnums += ([from.to_i, 1].max..[to.to_i, 1].max).to_a
-          else
-            pgnums << entry.to_i
-          end
-        end
-
-        pgnums
-      end
-
-      def get_char code
-        (code.start_with? '\u') ? ([((code.slice 2, code.length).to_i 16)].pack 'U1') : code
-      end
-
-      def create_prototype
+      def create_scratch_prototype
         @label = :scratch
         @save_state = nil
         @scratch_depth = 0
@@ -4971,7 +4969,7 @@ module Asciidoctor
       end
 
       def init_scratch originator
-        @prototype = originator.instance_variable_get :@prototype
+        @scratch_prototype = originator.instance_variable_get :@scratch_prototype
         @tmp_files = originator.instance_variable_get :@tmp_files
         text_formatter.scratch = true
         self
@@ -4996,7 +4994,7 @@ module Asciidoctor
 
       def clear_scratch
         @scratch_depth = 0
-        @save_state = @prototype = @scratch = nil
+        @save_state = @scratch_prototype = @scratch = nil
       end
     end
   end