asciidoctor-lists-extended 1.1.7 → 1.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c214e4770c4445a9daa0344bcf022895ce0f4172dfc3a1c1c13c01f36b01faa8
-  data.tar.gz: 80c15b6379aff0506b06f9b488cc6ac518f97048b775cf99c49271731552c9ce
+  metadata.gz: e5957e1ace3164d5cb55fd2a56ec3bdc815b51f20d11a4b1ccf2ce90266f5601
+  data.tar.gz: 9aa5f6a0fd2d1dbe1aa708443117ae531f05408d32bb79cdf1dd6ceec01b6a1a
 SHA512:
-  metadata.gz: fd41e36b82b84c0d3ebb3bcbf5438d1a27f67b9f6d57d83085c178191e42820a30418c55928fff84b53f608459d1fa96daa77cfef13cf416157bcbbdc861fb8b
-  data.tar.gz: aa7e49c4c3d4b80638f5dd7e5f4bd9a75eecd3d58d85c129dc313f6f69ae79d31b73b0e60c400f7353846afbabbb3b44790d95e0010cbc9611db50a6185d6c8d
+  metadata.gz: '06381153db44ca502bc4e6b121bb1df9815b0beb1733dd143f8c6d45744684f6de7b1a4508d9069b8cdbdc1b548858748d722277c71aa72adec3be615fc6a7f4'
+  data.tar.gz: 07e3de4563cff3a8688520829ab6dbda68f3376d3d03ae0ef2e5c738db0a07c598d5ad6cbc508e7eacc7d09494ceec0e576e4789e1ea10f3f86eddd660f02849

data/README.adoc

@@ -8,6 +8,8 @@ A converter-aware asciidoctor extension that generates a *List of Figures*, *Lis
 Replaces and supersedes `asciidoctor-pdf-lofte`.
 Compatible with the `asciidoctor-lists` macro syntax.
 
+https://baiyibai-antora.gitlab.io
+
 == Preview
 
 .Table of Contents with List of Figures, List of Tables, and List of Examples entries
@@ -35,27 +37,80 @@ image::test/images/pdf-outline.png[PDF bookmark outline panel,pdfwidth=100%]
 
 == Installation
 
-Add to the `Gemfile`:
+=== Ruby (PDF + HTML5)
+
+[source,bash]
+----
+gem install asciidoctor-lists-extended
+----
+
+Add to a `Gemfile`:
 
 [source,ruby]
 ----
-gem 'asciidoctor-lists-extended', path: '/path/to/asciidoctor-lists-extended'
+gem 'asciidoctor-lists-extended'
+----
+
+Require on the command line:
+
+[source,bash]
+----
+asciidoctor-pdf -r asciidoctor-lists-extended document.adoc
+asciidoctor    -r asciidoctor-lists-extended document.adoc
 ----
 
-Or require directly:
+=== Node.js / npm (HTML5, Antora, VSCode)
 
 [source,bash]
 ----
-asciidoctor-pdf -r /path/to/lib/asciidoctor-lists-extended.rb document.adoc
+npm install asciidoctor-lists-extended
+----
+
+==== Antora
+
+Add to the Antora site's `package.json` dependencies, then reference in the playbook
+under `asciidoc:` — *not* under `antora:` (those are pipeline hooks, not Asciidoctor.js extensions):
+
+[source,yaml]
+----
+asciidoc:
+  extensions:
+    - asciidoctor-lists-extended
 ----
 
-For HTML5 only (no `asciidoctor-pdf` needed):
+The `list-of::` macro is then available in all AsciiDoc source files processed by that playbook.
+
+==== VSCode
+
+Install globally on the machine hosting the workspace (local or Remote-SSH server):
 
 [source,bash]
 ----
-asciidoctor -r /path/to/lib/asciidoctor-lists-extended.rb document.adoc
+npm install -g asciidoctor-lists-extended
+----
+
+Add to `.vscode/settings.json`:
+
+[source,json]
+----
+{
+  "asciidoc.asciidoctorExtensions": ["asciidoctor-lists-extended"]
+}
+----
+
+For workspaces where a global install is not available, add a one-line shim at
+`.asciidoctor/lib/lists-extended.js`:
+
+[source,javascript]
+----
+module.exports = require('asciidoctor-lists-extended')
 ----
 
+The VSCode AsciiDoc extension auto-loads any `.js` file in `.asciidoctor/lib/`.
+
+NOTE: For Remote-SSH, the npm package must be installed on the *remote* machine.
+The VSCode AsciiDoc preview runs server-side.
+
 == Quick Start
 
 [source,asciidoc]

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

@@ -45,6 +45,11 @@ module Asciidoctor
           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'),
+          # site — force document-wide scope regardless of nesting depth.
+          # Needed in Antora assembled PDFs where pages are shifted one level deep
+          # (what was == Section in the source becomes === Subsection in the assembled
+          # document), causing scope_node_for to mis-classify the macro as chapter-scoped.
+          scope_global:         attrs.key?('site')            || pos_flags.include?('site'),
           caption_prefix:       attrs['caption_prefix'],
           title:                attrs['title'],
           entry_indent:         attrs['entry_indent']&.to_f,
@@ -85,7 +90,16 @@ module Asciidoctor
         end
 
         # PDF backend: UUID placeholders are handled by PDFConverterWithLists.
-        return if document.backend == 'pdf'
+        # allocate_toc/ink_toc only fire when the document has a toc attribute set.
+        # Warn here so the author sees a clear message instead of raw UUIDs in the PDF.
+        if document.backend == 'pdf'
+          unless document.attr?('toc')
+            logger.warn 'asciidoctor-lists-extended: list-of:: macros in PDF output require ' \
+                        'toc::[] in the document (or :toc: in the header); ' \
+                        'without it the list will render as a raw UUID placeholder.'
+          end
+          return
+        end
 
         # HTML5 and other backends: replace UUID placeholders with xref content.
         HtmlRenderer.new.render(document)

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

@@ -22,6 +22,7 @@ module Asciidoctor
           hide_empty_section = params[:hide_empty_section]
 
           scope    = scope_node_for(block, document)
+          scope    = document if params[:scope_global]
           elements = scope.find_by(
             traverse_documents: true,
             context: params[:element].to_sym

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

@@ -59,9 +59,13 @@ module Asciidoctor
       # allocate_toc hook
       # -----------------------------------------------------------------------
       # Called by asciidoctor-pdf early in document generation to reserve page
-      # space for the ToC.  We call super first (allocate the real ToC), then
-      # iterate over all list-of:: macros and allocate space for each list.
+      # space for the ToC.  We mark sections that contain empty list-of:: macros
+      # before calling super so that super's dry-run of ink_toc does not count
+      # those sections as ToC entries and over-allocate ToC pages.  Those sections
+      # are removed entirely by collect_and_allocate_lists, so the marker never
+      # reaches the final document.
       def allocate_toc(doc, num_levels, toc_start_cursor, break_after_toc)
+        mark_empty_list_sections doc
         result = super
         collect_and_allocate_lists doc, num_levels, toc_start_cursor, break_after_toc
         result
@@ -151,11 +155,13 @@ module Asciidoctor
       # -----------------------------------------------------------------------
       # get_entries_for_toc override
       # -----------------------------------------------------------------------
-      # Filters out virtual list sections marked with 'list-exclude-from-toc'
-      # so they are hidden from the rendered Table of Contents while remaining
-      # present in doc.sections (and therefore still visible in the PDF outline).
+      # Filters out:
+      #   list-exclude-from-toc     — virtual list sections the author opted out of the ToC
+      #   list-toc-measure-skip     — original sections for empty lists, temporarily marked
+      #                               by mark_empty_list_sections so allocate_toc's dry-run
+      #                               does not over-allocate ToC pages for them
       def get_entries_for_toc(node)
-        super.reject { |s| s.attr? 'list-exclude-from-toc' }
+        super.reject { |s| (s.attr? 'list-exclude-from-toc') || (s.attr? 'list-toc-measure-skip') }
       end
 
       # -----------------------------------------------------------------------
@@ -270,6 +276,34 @@ module Asciidoctor
 
       private
 
+      # -----------------------------------------------------------------------
+      # mark_empty_list_sections
+      # -----------------------------------------------------------------------
+      # Scans the document for document-wide list-of:: macros whose element type
+      # has no captioned/titled entries.  Marks the parent section of each such
+      # macro with the 'list-toc-measure-skip' attribute so that
+      # get_entries_for_toc excludes it during allocate_toc's dry-run measurement.
+      #
+      # collect_and_allocate_lists removes these sections entirely before the real
+      # ink_toc pass, so the attribute never persists into the final document.
+      def mark_empty_list_sections(doc)
+        doc.find_by do |b|
+          b.content_model == :simple &&
+            b.lines.size == 1 &&
+            ListMacroAttributes.key?(b.lines[0])
+        end.each do |block|
+          uuid       = block.lines[0]
+          config     = ListMacroAttributes[uuid]
+          scope_node = scope_node_for(block)
+          scope_node = doc if config[:scope_global]
+          next unless scope_node.equal?(doc)
+          next unless get_list_entries(scope_node, config[:element]).empty?
+
+          parent = block.parent
+          parent.set_attr 'list-toc-measure-skip', '' if parent.context == :section
+        end
+      end
+
       # -----------------------------------------------------------------------
       # collect_and_allocate_lists
       # -----------------------------------------------------------------------
@@ -288,6 +322,7 @@ module Asciidoctor
           uuid       = block.lines[0]
           config     = ListMacroAttributes[uuid]
           scope_node = scope_node_for(block)
+          scope_node = doc if config[:scope_global]
           entries    = get_list_entries(scope_node, config[:element])
           parent     = block.parent
 

metadata

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