asciidoctor-lists-extended 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1f0396e93370444193a1258530dd32f81db35dddaedc4c911a31655d94d5e2c
-  data.tar.gz: bbd4f0412e6b11fcfc1bb39b38a2cd9932c8738a740d8c6b693f4185c03c0566
+  metadata.gz: 2fef48386d4e8e43dc4b346f18f0eacc159e4660ae72a37b7d0e309bcee7f1b5
+  data.tar.gz: 794aa84d51d840cfcf72deea61a208030070c9efc0779d1ee70c4bdf2997f655
 SHA512:
-  metadata.gz: 9970ef9f04375ee8e446abb219171880806ac09bdc09f1909f0830eda569e37191188cd195813185339e56b31ccaaf6446f835415f77d5adaf912b6bf032aee3
-  data.tar.gz: fe43e888bba80b85b9212f24df7bed543224e510f22e4b40aefd754eeacf27b0e5e22220d2bc9a3d70e684dacab1e00d49ab120547b74382b6ad9bdc86bda824
+  metadata.gz: e2a3f7a9859c3fcb6a83b552b3a23138cc992c88349d9ea2202541cffc46425e4bb579fe8fe04cb742421c9810e6a76d96260fb8ae3f5fa170aeef27a48d0bb7
+  data.tar.gz: d0821487c0d6510278fa8148a3c615682657228b61d9052b1460de9f23e45f789def711dfa0834da30d46adeadde73a3be77f366fd3a1bba1858861c88d50f41

data/README.adoc

@@ -112,6 +112,14 @@ Kept as an explicit opt-in for backwards compatibility with the original `asciid
 
 |`exclude_from_outline`
 |PDF only. Omits this list from the PDF bookmark outline while keeping it in the Table of Contents.
+
+|`strip_period`
+|PDF only. Removes the trailing period from caption signifiers, e.g. "Table 1." → "Table 1".
+Overrides the theme `caption_style` for this macro (equivalent to `caption_style: strip`).
+
+|`split_caption`
+|PDF only. Renders the caption signifier (e.g. "Table 1") at the left margin and the title indented at the `entry_indent` offset.
+Overrides the theme `caption_style` for this macro (equivalent to `caption_style: split`).
 |===
 
 === Named Parameters
@@ -127,6 +135,14 @@ Kept as an explicit opt-in for backwards compatibility with the original `asciid
 |`caption_prefix`
 |Both
 |Override the caption prefix label (e.g. `"Figure"`). Currently informational; caption is taken from the element's own `captioned_title`.
+
+|`entry_indent`
+|PDF
+|Numeric (pt). Override the theme `entry_indent` for this macro only.
+
+|`first_entry_margin`
+|PDF
+|Numeric (pt). Override the theme `first_entry_margin` for this macro only.
 |===
 
 === Supported Element Types
@@ -157,6 +173,18 @@ Elements *without* a title or caption are silently skipped.
 
 == Document Attributes
 
+=== Extension Attributes
+
+[cols="1,3"]
+|===
+|Attribute |Effect
+
+|`:toc-in-toc:`
+|PDF only. Inserts the Table of Contents itself as the first entry in the PDF ToC and bookmark outline, before any `list-of::` sections.
+The entry title is taken from the `:toc-title:` attribute (default: `Table of Contents`).
+
+|===
+
 === Caption Attributes (standard Asciidoctor)
 
 [source,asciidoc]
@@ -179,9 +207,12 @@ In PDF mode the extension hooks into `asciidoctor-pdf`'s ToC allocation/renderin
 
 === Placement
 
-All lists are placed in the *front matter* (directly after the ToC) regardless of where the `list-of::` macros appear in the source.
+Document-wide lists (macros inside a top-level `== …` section) are placed in the *front matter* (directly after the ToC) regardless of where in the source the `list-of::` macros appear.
 The macro order in the source determines the order of the lists in the front matter.
 
+When the top-level section that contains a `list-of::` macro also has other content — admonitions, paragraphs, or other blocks — those blocks are moved to the front matter too and rendered between the list heading and the first entry.
+The enclosing section is then removed from the body so it does not appear twice.
+
 You can place `list-of::` macros inside any subsection to generate *section-scoped* lists.
 The scope is determined automatically from where the macro appears in the document hierarchy:
 
@@ -254,6 +285,65 @@ image_list_title:
   text_align: center
 ----
 
+=== Theme Keys (`asciidoctor_lists_extended`)
+
+List entry rendering can be configured globally via your PDF theme YAML under the `asciidoctor_lists_extended` namespace.
+Macro-level attributes always override theme values.
+
+[source,yaml]
+----
+asciidoctor_lists_extended:
+  caption_style: split              # default | split | strip
+  entry_indent: 58                  # pt — left indent for entry title text
+  first_entry_margin: 10            # pt — vertical space before the first entry
+  image:
+    exclude_from_toc: false         # default exclude for list-of::image[]
+    exclude_from_outline: false
+  table:
+    exclude_from_toc: false
+    exclude_from_outline: false
+  listing:
+    exclude_from_toc: false
+    exclude_from_outline: false
+  example:
+    exclude_from_toc: false
+    exclude_from_outline: false
+----
+
+[cols="2,1,4"]
+|===
+|Key |Default |Description
+
+|`caption_style`
+|`default`
+|Controls how captioned list entries are rendered. +
+`default` — full `captioned_title` as one string. +
+`split` — signifier (e.g. "Table 1") at left margin, title indented at `entry_indent`. +
+`strip` — full title with trailing period removed from the signifier.
+
+|`entry_indent`
+|`0`
+|Left indent (pt) for entry text.
+In `split` mode the signifier stays at 0 and the title starts at this offset.
+In `default`/`strip` modes the entire entry is indented.
+
+|`first_entry_margin`
+|`0`
+|Extra vertical space (pt) inserted before the first entry of each list.
+
+|`<element>.exclude_from_toc`
+|`false`
+|Per-element-type default for omitting lists from the PDF Table of Contents.
+Overridden by the `exclude_from_toc` positional flag on individual macros.
+
+|`<element>.exclude_from_outline`
+|`false`
+|Per-element-type default for omitting lists from the PDF bookmark outline.
+Overridden by the `exclude_from_outline` positional flag on individual macros.
+|===
+
+**Override priority:** macro attribute > theme key > built-in default.
+
 == HTML Behaviour
 
 In HTML5 mode the macro is replaced *in-place* with a list of cross-reference links:
@@ -301,12 +391,6 @@ image::arch.png[]
 |timeout |30 |Seconds
 |===
 
-.bootstrap.sh
-[source,bash]
-----
-#!/bin/bash
-echo "Starting..."
-----
 ----
 <1> Plain usage — collects all images with captions. Appears in PDF ToC and outline by default.
 <2> If no tables exist, the "List of Tables" section is omitted entirely.
@@ -368,7 +452,12 @@ The `list-of::` macros render as `<ul>` lists with `<a href="#…">` links.
 
 |`:include-lists-in-toc:`
 |Lists are included in the PDF ToC and bookmark outline by default.
-Use `exclude_from_toc` or `exclude_from_outline` on individual macros to opt out.
+Use `exclude_from_toc` or `exclude_from_outline` on individual macros to opt out, or set per-element-type defaults via theme keys.
+To add "Table of Contents" itself as the first entry in the ToC/outline, set `:toc-in-toc:`.
+
+|Hardcoded line height / spacing / indentation in lofte converter
+|Theme-driven via `asciidoctor_lists_extended` YAML keys (`caption_style`, `entry_indent`, `first_entry_margin`).
+Macro-level overrides (`split_caption`, `strip_period`, `entry_indent=X`, `first_entry_margin=X`) still available.
 
 |Required `[#anchor]` on every block
 |Auto-generated — no anchors needed
@@ -377,7 +466,13 @@ Use `exclude_from_toc` or `exclude_from_outline` on individual macros to opt out
 |HTML5 + PDF
 
 |4 copy-pasted converter classes (~1200 lines)
-|1 unified converter class (~320 lines)
+|1 unified converter class (~550 lines)
+
+|`PDFConverterModifyRunningContent` (custom running content)
+|Virtual sections get `pdf-page-start` automatically — base `ink_running_content` picks up list titles as `{chapter-title}`.
+
+|`ModifyOutline` (custom outline builder)
+|`add_outline_level` override filters excluded lists and strips trailing dots from section numbers.
 |===
 
 == Architecture Overview
@@ -447,6 +542,27 @@ Keeping the drawing logic in a separate mixin makes that reuse clean: the conver
 . *`add_outline_level` override* (`pdf_converter.rb`) — called by asciidoctor-pdf when building the PDF bookmark outline.
   Filters out any virtual list sections marked with `list-exclude-from-outline` before delegating to `super`, implementing the `exclude_from_outline` flag.
 
+== Known Limitations
+
+`toc-placement: macro`::
+  When `:toc-placement: macro` is set, asciidoctor-pdf defers its `allocate_toc` call to
+  the inline `toc::[]` macro during body rendering.
+  This extension's `allocate_toc` override therefore never runs, so UUID placeholder paragraphs
+  are not processed and appear as raw text in the output.
+  Use the default `:toc:` attribute (which places the ToC at the top of the front matter)
+  instead.
+
+Bare macros excluded from ToC and outline::
+  When a `list-of::` macro is placed outside any section heading (document preamble), the
+  generated list has no title and is therefore excluded from the PDF Table of Contents and
+  bookmark outline.
+  Wrap the macro in a `==` section to give it a title and have it appear in the ToC.
+
+CJK font support::
+  asciidoctor-pdf does not bundle CJK fonts.
+  Documents using Chinese, Japanese, or Korean text require a custom PDF theme that specifies
+  a CJK-capable font family.
+
 == Licence
 
 MIT

data/lib/asciidoctor-lists-extended/extensions.rb

@@ -18,8 +18,12 @@ module Asciidoctor
     #   hide_empty_section   — remove the parent section if no entries found (positional)
     #   exclude_from_toc     — omit this list from the PDF Table of Contents and outline (positional, PDF only)
     #   exclude_from_outline — omit this list from the PDF bookmark outline only (positional, PDF only)
+    #   strip_period         — remove the trailing period from caption signifiers, e.g. "Table 1." → "Table 1" (positional)
+    #   split_caption        — render signifier and title separately with indentation in list entries (positional, PDF only)
     #   caption_prefix       — override the caption prefix (e.g. "Figure")
     #   title                — override the list heading
+    #   entry_indent         — (named, numeric) override theme entry indent (pt)
+    #   first_entry_margin   — (named, numeric) override theme first-entry margin (pt)
     #
     # Example:
     #   list-of::image[]
@@ -39,8 +43,12 @@ module Asciidoctor
           hide_empty_section:   attrs['hide_empty_section']   || pos_flags.include?('hide_empty_section'),
           exclude_from_toc:     attrs['exclude_from_toc']     || pos_flags.include?('exclude_from_toc'),
           exclude_from_outline: attrs['exclude_from_outline'] || pos_flags.include?('exclude_from_outline'),
+          strip_period:         attrs['strip_period']         || pos_flags.include?('strip_period'),
+          split_caption:        attrs['split_caption']        || pos_flags.include?('split_caption'),
           caption_prefix:       attrs['caption_prefix'],
           title:                attrs['title'],
+          entry_indent:         attrs['entry_indent']&.to_f,
+          first_entry_margin:   attrs['first_entry_margin']&.to_f,
         }
         create_paragraph parent, uuid, {}
       end
@@ -68,6 +76,7 @@ module Asciidoctor
             .find_by(traverse_documents: true, context: config[:element].to_sym)
             .each do |element|
               next unless element.caption || element.title
+              next if element.style == 'discrete'
               next if element.id
 
               element.id = SecureRandom.uuid

data/lib/asciidoctor-lists-extended/html_renderer.rb

@@ -27,23 +27,27 @@ module Asciidoctor
             context: params[:element].to_sym
           )
 
-          titled_elements = elements.select { |e| e.caption || e.title }
+          titled_elements = elements.select { |e| (e.caption || e.title) && e.style != 'discrete' }
 
           if titled_elements.empty? && hide_empty_section
             block.parent.parent.blocks.delete(block.parent)
             next
           end
 
+          strip_period = params[:strip_period]
+
           references_asciidoc = titled_elements.map do |element|
+            caption_text = element.caption&.rstrip
+            caption_text = caption_text.sub(/\.\z/, '') if strip_period && caption_text
             if enhanced_rendering
-              if element.caption
-                %(xref:#{element.id}[#{element.caption.rstrip}] #{element.instance_variable_get(:@title)} +)
+              if caption_text
+                %(xref:#{element.id}[#{caption_text}] #{element.instance_variable_get(:@title)} +)
               else
                 %(xref:#{element.id}[#{element.instance_variable_get(:@title)}] +)
               end
             else
-              if element.caption
-                %(xref:#{element.id}[#{element.caption.rstrip}] #{element.title} +)
+              if caption_text
+                %(xref:#{element.id}[#{caption_text}] #{element.title} +)
               else
                 %(xref:#{element.id}[#{element.title}] +)
               end

data/lib/asciidoctor-lists-extended/pdf_converter.rb

@@ -33,6 +33,10 @@ module Asciidoctor
         @inline_render_positions       = {}   # UUID → deferred render position (page + cursor)
         @inline_num_front_matter_pages = 0    # saved from ink_toc for inline page-number math
         @rendering_list                = false
+        @list_strip_period             = false
+        @list_split_caption            = false
+        @list_entry_indent             = nil
+        @list_first_entry_margin       = nil
         @list_toc_insert_idx           = 0
       end
 
@@ -75,6 +79,17 @@ module Asciidoctor
         @inline_num_front_matter_pages = num_front_matter_pages
         @list_toc_insert_idx = 0
 
+        # toc-in-toc: insert the Table of Contents itself as the first entry in
+        # the PDF ToC, before any list-of:: sections.  Excluded from the bookmark
+        # outline because asciidoctor-pdf's add_outline already adds a ToC bookmark.
+        if (doc.attr? 'toc-in-toc') && @toc_extent
+          toc_entry_title = doc.attr('toc-title') || 'Table of Contents'
+          insert_list_into_toc_section doc, toc_entry_title, @toc_extent.page_range,
+            '_toc_in_toc', @list_toc_insert_idx,
+            exclude_from_outline: true
+          @list_toc_insert_idx += 1
+        end
+
         @list_configs_ordered.each do |config|
           extent = @list_extents[config[:uuid]]
           next unless extent
@@ -84,10 +99,14 @@ module Asciidoctor
           list_title     = config[:title] || config[:section_title]
           list_page_nums = extent.page_range
           list_id        = "_list_of_#{config[:element].tr('-', '_')}"
-          insert_list_into_toc_section doc, list_title, list_page_nums, list_id, @list_toc_insert_idx,
-            exclude_from_toc:     config[:exclude_from_toc],
-            exclude_from_outline: config[:exclude_from_outline]
-          @list_toc_insert_idx += 1
+          # Bare macros (no parent section and no title= attribute) have no
+          # meaningful label for the ToC or outline — skip the virtual section.
+          unless list_title.nil_or_empty?
+            insert_list_into_toc_section doc, list_title, list_page_nums, list_id, @list_toc_insert_idx,
+              exclude_from_toc:     resolve_exclude_from_toc(config),
+              exclude_from_outline: resolve_exclude_from_outline(config)
+            @list_toc_insert_idx += 1
+          end
         end
 
         result = super
@@ -102,11 +121,22 @@ module Asciidoctor
             entries = get_list_entries(pos[:config][:scope_node], pos[:config][:element])
             next if entries.empty?
             entries.each { |e| e.level = 2 if e.title }
+            caption_style    = resolve_caption_style(pos[:config])
+            entry_indent     = pos[:config][:entry_indent] || @theme.asciidoctor_lists_extended_entry_indent
+            first_entry_margin = pos[:config][:first_entry_margin] || @theme.asciidoctor_lists_extended_first_entry_margin
             begin
-              @rendering_list = true
+              @rendering_list          = true
+              @list_strip_period       = (caption_style == 'strip')
+              @list_split_caption      = (caption_style == 'split')
+              @list_entry_indent       = entry_indent
+              @list_first_entry_margin = first_entry_margin
               ink_toc_level entries, pos[:num_levels], pos[:dot_leader], num_front_matter_pages
             ensure
-              @rendering_list = false
+              @rendering_list          = false
+              @list_strip_period       = false
+              @list_split_caption      = false
+              @list_entry_indent       = nil
+              @list_first_entry_margin = nil
             end
           end
           go_to_page page_count
@@ -132,8 +162,29 @@ module Asciidoctor
       # before delegating to the parent implementation, which builds PDF bookmarks.
       # This lets exclude_from_outline keep a list in the ToC while hiding it
       # from the PDF bookmark outline.
+      #
+      # Also strips trailing dots from numbered section titles so outline entries
+      # read "1.2.3 Title" instead of "1.2.3. Title" (ported from the former
+      # ModifyOutline converter).
       def add_outline_level(outline, sections, num_levels, expand_levels)
-        super outline, sections.reject { |s| s.attr? 'list-exclude-from-outline' }, num_levels, expand_levels
+        filtered = sections.reject { |s| s.attr? 'list-exclude-from-outline' }
+        patched_sects = []
+        filtered.each do |sect|
+          next unless sect.context == :section
+          raw_title = sect.numbered_title(formal: true)
+          cleaned = if raw_title =~ /\A([\d.]+)\.\s+(.*)\z/
+            "#{$1} #{$2}"
+          elsif raw_title =~ /\A([\d.]+)\.\z/
+            $1
+          end
+          if cleaned
+            sect.define_singleton_method(:numbered_title) { |**_opts| cleaned }
+            patched_sects << sect
+          end
+        end
+        super outline, filtered, num_levels, expand_levels
+      ensure
+        patched_sects&.each { |s| s.singleton_class.send(:remove_method, :numbered_title) }
       end
 
       # -----------------------------------------------------------------------
@@ -174,22 +225,42 @@ module Asciidoctor
             num_levels = @theme.toc_levels || 2
             dot_leader = build_dot_leader_config(num_levels)
 
+            caption_style      = resolve_caption_style(config)
+            entry_indent       = config[:entry_indent] || @theme.asciidoctor_lists_extended_entry_indent
+            first_entry_margin = config[:first_entry_margin] || @theme.asciidoctor_lists_extended_first_entry_margin
+
             if scratch?
               # Scratch pass (e.g. heading orphan detection): measure space only.
               begin
-                @rendering_list = true
+                @rendering_list          = true
+                @list_strip_period       = (caption_style == 'strip')
+                @list_split_caption      = (caption_style == 'split')
+                @list_entry_indent       = entry_indent
+                @list_first_entry_margin = first_entry_margin
                 ink_toc_level entries, num_levels, dot_leader, 0
               ensure
-                @rendering_list = false
+                @rendering_list          = false
+                @list_strip_period       = false
+                @list_split_caption      = false
+                @list_entry_indent       = nil
+                @list_first_entry_margin = nil
               end
             else
               # Real pass: measure via dry_run, reserve blank space, save position.
               extent = dry_run(onto: self) do
                 begin
-                  @rendering_list = true
+                  @rendering_list          = true
+                  @list_strip_period       = (caption_style == 'strip')
+                  @list_split_caption      = (caption_style == 'split')
+                  @list_entry_indent       = entry_indent
+                  @list_first_entry_margin = first_entry_margin
                   ink_toc_level entries, num_levels, dot_leader, 0
                 ensure
-                  @rendering_list = false
+                  @rendering_list          = false
+                  @list_strip_period       = false
+                  @list_split_caption      = false
+                  @list_entry_indent       = nil
+                  @list_first_entry_margin = nil
                 end
               end
 
@@ -241,16 +312,26 @@ module Asciidoctor
           if scope_node.equal?(doc)
             # ── Document-wide macro ────────────────────────────────────────
             # Remove from body and render in PDF front matter after the ToC.
-            # Capture the parent section title first — it becomes the list heading.
+            # Capture the parent section title (list heading) and any extra
+            # sibling blocks (admonitions, paragraphs, etc.) so they are
+            # rendered in the front matter alongside the list rather than left
+            # as orphaned content in the body.
             section_title = (parent.context == :section) ? parent.title : nil
+            section_body  = parent.context == :section ?
+              parent.blocks.reject { |b| b.object_id == block.object_id } : []
+            # Page-break blocks (<<<) must be deleted from the section but must NOT
+            # be rendered in front matter — they only existed to separate list sections
+            # from body chapters.
+            extra_blocks  = section_body.reject { |b| b.context == :page_break }
+
             parent.blocks.delete(block)
-            if parent.context == :section && parent.blocks.empty?
-              parent.parent&.blocks&.delete(parent)
-            end
+            section_body.each { |b| parent.blocks.delete(b) }
+            parent.parent&.blocks&.delete(parent) if parent.context == :section && parent.blocks.empty?
 
             next if entries.empty?
 
-            config_with_uuid = config.merge(uuid: uuid, section_title: section_title, scope_node: scope_node)
+            config_with_uuid = config.merge(uuid: uuid, section_title: section_title,
+              section_blocks: extra_blocks, scope_node: scope_node)
             @list_configs_ordered << config_with_uuid
             @list_extents[uuid] = allocate_list(doc, config_with_uuid, num_levels, start_cursor, break_after)
           else
@@ -262,6 +343,12 @@ module Asciidoctor
             @inline_list_configs[uuid] = config_with_uuid
           end
         end
+
+        # Strip leading page-break blocks left over after list sections were
+        # removed.  A `<<<` placed between the last list section and the first
+        # chapter now sits orphaned at the document level; without this cleanup
+        # it renders as a blank page before Chapter 1.
+        doc.blocks.shift while doc.blocks.first&.context == :page_break
       end
 
       # -----------------------------------------------------------------------
@@ -271,17 +358,12 @@ module Asciidoctor
       # that many pages.  Follows the same pattern as rhrev's
       # allocate_revision_history_extent and asciidoctor-pdf-lofte's allocate_lof.
       def allocate_list(doc, config, num_levels, _start_cursor, break_after)
-        to_page = nil
-        extent  = dry_run onto: self do
-          to_page = ink_list(doc, config, nil, num_levels, 0).last
+        extent = dry_run onto: self do
+          ink_list(doc, config, nil, num_levels, 0)
           theme_margin :block, :bottom unless break_after
         end
 
-        if to_page && to_page > extent.to.page
-          extent.to.page   = to_page
-          extent.to.cursor = bounds.height
-        end
-
+        page_before = page_number
         if break_after
           extent.each_page { start_new_page }
         else
@@ -333,6 +415,7 @@ module Asciidoctor
       def ink_list_toc_level(entries, num_levels, dot_leader, num_front_matter_pages)
         toc_font_info  = theme_font(:toc) { { font: font, size: @font_size } }
         hanging_indent = @theme.toc_hanging_indent
+        is_first_entry = true
 
         entries.each do |entry|
           next if (num_levels_for_entry = (entry.attr 'toclevels', num_levels).to_i) <
@@ -346,26 +429,69 @@ module Asciidoctor
 
           # For captioned blocks (image, table, example, listing, custom) prefer
           # captioned_title, e.g. "Figure 1. My Diagram" over "My Diagram".
+          # When strip_period is active, rebuild from caption without the trailing
+          # period, e.g. "Figure 1 My Diagram".
           if entry.context != :section && entry.respond_to?(:captioned_title)
-            captioned = entry.captioned_title
-            entry_title = captioned unless captioned.nil_or_empty?
+            if @list_strip_period && entry.caption
+              stripped_caption = entry.caption.sub(/\.\s*\z/, ' ')
+              entry_title = "#{stripped_caption}#{entry.title}"
+            else
+              captioned = entry.captioned_title
+              entry_title = captioned unless captioned.nil_or_empty?
+            end
           end
 
           next if entry_title.nil_or_empty?
 
+          # Apply first_entry_margin before the very first entry
+          if is_first_entry && @list_first_entry_margin
+            move_down @list_first_entry_margin
+            is_first_entry = false
+          else
+            is_first_entry = false
+          end
+
+          # Determine if we should split signifier from title
+          split_parts = nil
+          if @list_split_caption && entry.context != :section && entry.caption
+            parts = entry_title.split('. ', 2)
+            split_parts = { signifier: parts[0], title: parts[1] } if parts.length == 2
+          end
+
           theme_font :toc, level: entry_level do
-            entry_title = transform_text entry_title, @text_transform if @text_transform
             pgnum_label_placeholder_width = rendered_width_of_string '0' * @toc_max_pagenum_digits
 
+            # Resolve effective entry indent: macro override > theme > default
+            effective_indent = @list_entry_indent || 0
+
+            if split_parts
+              split_indent = effective_indent > 0 ? effective_indent : (bounds.width * 0.115)
+              split_parts[:signifier] = transform_text(split_parts[:signifier], @text_transform) if @text_transform
+              split_parts[:title]     = transform_text(split_parts[:title], @text_transform)     if @text_transform
+            else
+              entry_title = transform_text entry_title, @text_transform if @text_transform
+            end
+
             if scratch?
               # Dry-run pass: measure space only
-              indent 0, pgnum_label_placeholder_width do
-                ink_prose entry_title,
-                  anchor:               true,
-                  normalize:            false,
-                  hanging_indent:       hanging_indent,
-                  normalize_line_height: true,
-                  margin:               0
+              if split_parts
+                indent split_indent, pgnum_label_placeholder_width do
+                  ink_prose split_parts[:title],
+                    anchor:               true,
+                    normalize:            false,
+                    hanging_indent:       hanging_indent,
+                    normalize_line_height: true,
+                    margin:               0
+                end
+              else
+                indent effective_indent, pgnum_label_placeholder_width do
+                  ink_prose entry_title,
+                    anchor:               true,
+                    normalize:            false,
+                    hanging_indent:       hanging_indent,
+                    normalize_line_height: true,
+                    margin:               0
+                end
               end
             else
               # Real render pass: resolve page number and draw dot leader
@@ -392,27 +518,65 @@ module Asciidoctor
 
               entry_title_inherited = (apply_text_decoration ::Set.new, :toc, entry_level)
                 .merge(anchor: entry_anchor, color: @font_color)
-              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
-                fragment_positions = entry_title_fragments.map do |fragment|
-                  fp = ::Asciidoctor::PDF::FormattedText::FragmentPositionRenderer.new
-                  (fragment[:callback] ||= []) << fp
-                  fp
-                end
-                typeset_formatted_text entry_title_fragments, line_metrics,
-                  hanging_indent:       hanging_indent,
+              if split_parts
+                # ── Split caption: signifier at left, title indented ──
+                split_indent = effective_indent > 0 ? effective_indent : (bounds.width * 0.115)
+
+                # Phase 1: Render signifier (e.g. "Table 1") at normal position
+                signifier_fragments = text_formatter.format split_parts[:signifier],
+                  inherited: entry_title_inherited
+                typeset_formatted_text signifier_fragments, line_metrics,
                   normalize_line_height: true
-                last_fp = fragment_positions.select(&:page_number).last
-                break unless last_fp
-
-                start_dots = last_fp.right + hanging_indent
-                last_frag_cursor = last_fp.top + line_metrics.padding_top
-                if last_fp.page_number > start_page_number ||
-                   (start_cursor - last_frag_cursor) > line_metrics.height
-                  start_cursor = last_frag_cursor
+                move_cursor_to start_cursor
+
+                # Phase 2: Render title indented, with fragment tracking for dot leaders
+                indent split_indent, pgnum_label_placeholder_width do
+                  title_fragments = text_formatter.format split_parts[:title],
+                    inherited: entry_title_inherited
+                  fragment_positions = title_fragments.map do |fragment|
+                    fp = ::Asciidoctor::PDF::FormattedText::FragmentPositionRenderer.new
+                    (fragment[:callback] ||= []) << fp
+                    fp
+                  end
+                  typeset_formatted_text title_fragments, line_metrics,
+                    hanging_indent:       hanging_indent,
+                    normalize_line_height: true
+                  last_fp = fragment_positions.select(&:page_number).last
+                  break unless last_fp
+
+                  # Adjust start_dots to full-bounds coordinates
+                  start_dots = last_fp.right + hanging_indent + split_indent
+                  last_frag_cursor = last_fp.top + line_metrics.padding_top
+                  if last_fp.page_number > start_page_number ||
+                     (start_cursor - last_frag_cursor) > line_metrics.height
+                    start_cursor = last_frag_cursor
+                  end
+                end
+              else
+                # ── Normal (non-split) rendering ──
+                entry_title_fragments = text_formatter.format entry_title,
+                  inherited: entry_title_inherited
+
+                indent effective_indent, pgnum_label_placeholder_width do
+                  fragment_positions = entry_title_fragments.map do |fragment|
+                    fp = ::Asciidoctor::PDF::FormattedText::FragmentPositionRenderer.new
+                    (fragment[:callback] ||= []) << fp
+                    fp
+                  end
+                  typeset_formatted_text entry_title_fragments, line_metrics,
+                    hanging_indent:       hanging_indent,
+                    normalize_line_height: true
+                  last_fp = fragment_positions.select(&:page_number).last
+                  break unless last_fp
+
+                  start_dots = last_fp.right + hanging_indent + effective_indent
+                  last_frag_cursor = last_fp.top + line_metrics.padding_top
+                  if last_fp.page_number > start_page_number ||
+                     (start_cursor - last_frag_cursor) > line_metrics.height
+                    start_cursor = last_frag_cursor
+                  end
                 end
               end
 

data/lib/asciidoctor-lists-extended/pdf_renderer.rb

@@ -40,14 +40,33 @@ module Asciidoctor
           end
         end
 
+        # Render any extra blocks from the original section (admonitions, paragraphs,
+        # etc.) that were captured alongside the list-of:: macro.  They appear after
+        # the heading but before the dot-leader entry rows.  Running during both the
+        # dry-run and real pass ensures the allocated space is correct.
+        (config[:section_blocks] || []).each { |b| convert b }
+
         unless num_levels < 0 || entries.empty?
           dot_leader = build_dot_leader_config(num_levels)
           theme_margin :toc, :top
+
+          caption_style    = resolve_caption_style(config)
+          entry_indent     = config[:entry_indent] || @theme.asciidoctor_lists_extended_entry_indent
+          first_entry_margin = config[:first_entry_margin] || @theme.asciidoctor_lists_extended_first_entry_margin
+
           begin
-            @rendering_list = true
+            @rendering_list          = true
+            @list_strip_period       = (caption_style == 'strip')
+            @list_split_caption      = (caption_style == 'split')
+            @list_entry_indent       = entry_indent
+            @list_first_entry_margin = first_entry_margin
             ink_toc_level entries, num_levels, dot_leader, num_front_matter_pages
           ensure
-            @rendering_list = false
+            @rendering_list          = false
+            @list_strip_period       = false
+            @list_split_caption      = false
+            @list_entry_indent       = nil
+            @list_first_entry_margin = nil
           end
         end
       end
@@ -58,7 +77,7 @@ module Asciidoctor
       def get_list_entries(scope_node, element_type)
         scope_node
           .find_by(traverse_documents: true, context: element_type.to_sym)
-          .select { |e| e.caption || e.title }
+          .select { |e| (e.caption || e.title) && e.style != 'discrete' }
       end
 
       # Insert a virtual Section node into the document AST at the correct position
@@ -78,7 +97,10 @@ module Asciidoctor
             toc_level           = doc.sections[0]&.level || 1
             base_idx            = 0
           end
-          toc_dest = toc_node.attr 'pdf-destination'
+          # NOTE: do NOT use toc_node.attr('pdf-destination') — that is the ToC
+          # page's own destination, which would make every list bookmark navigate
+          # back to the ToC page instead of the actual list page.
+          toc_dest = dest_top list_page_nums.first
         else
           grandparent_section = doc
           toc_level           = doc.sections[0]&.level || 1
@@ -90,12 +112,37 @@ module Asciidoctor
           attributes: { 'pdf-destination' => toc_dest }
         list_section.title = list_title
         list_section.id    = list_id
+        list_section.set_attr 'pdf-page-start', list_page_nums.first
         list_section.set_attr 'list-exclude-from-toc',     '' if exclude_from_toc
         list_section.set_attr 'list-exclude-from-outline', '' if exclude_from_outline
         grandparent_section.blocks.insert base_idx + insert_idx, list_section
         list_section
       end
 
+      # Resolve the effective caption_style for a list config.
+      # Priority: macro attribute > theme key > built-in default ('default').
+      def resolve_caption_style(config)
+        return 'split' if config[:split_caption]
+        return 'strip' if config[:strip_period]
+        @theme.asciidoctor_lists_extended_caption_style || 'default'
+      end
+
+      # Resolve whether a list should be excluded from the ToC.
+      # Priority: macro flag > per-element theme key > false.
+      def resolve_exclude_from_toc(config)
+        return true if config[:exclude_from_toc]
+        element_key = :"asciidoctor_lists_extended_#{config[:element].tr('-', '_')}_exclude_from_toc"
+        @theme.respond_to?(element_key) ? @theme.send(element_key) : false
+      end
+
+      # Resolve whether a list should be excluded from the PDF outline.
+      # Priority: macro flag > per-element theme key > false.
+      def resolve_exclude_from_outline(config)
+        return true if config[:exclude_from_outline]
+        element_key = :"asciidoctor_lists_extended_#{config[:element].tr('-', '_')}_exclude_from_outline"
+        @theme.respond_to?(element_key) ? @theme.send(element_key) : false
+      end
+
       private
 
       # Build the dot-leader configuration hash expected by ink_toc_level.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-lists-extended
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - 白一百 baiyibai