asciidoctor-autoterm 1.0.5 → 1.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c8192a4a53f24ff15393cef22492236d6008e36cf26ca7a32b7effa0e72dccd
-  data.tar.gz: c15610cd243fddd07394530cfc9ededc306e8c862f8fa85c3d9ff8b9786e7983
+  metadata.gz: c048e78c3879fd1f6499635746910ce0d10be44248308f9c3cd3e8a42dd0e273
+  data.tar.gz: 73c8ee930a26cd91a0c8e596877bbd62bda0751d1d78066521bdbe7721d19ff4
 SHA512:
-  metadata.gz: dfd54fb234911200003f93a2ba8e6194662a989ea2619c48a3e77cf5985c631089903c374ef22639fdf7c654daa61d8a318c762425f1106a8b804e60d2442443
-  data.tar.gz: 47b9476e439c8c0e3414738f0a69f95517fb9dd5da3feee2e72d5307d8aefe1e281cb56766b4578172b7ee1cb3603ce6a7d67d4a47891c9d7688792ffcb727a0
+  metadata.gz: af6a59f777c5c38859024888dffbcc5657cf159a9240daf1fdae69505a87aec7298ca24866bea236a9b5d27383a70afd0f0000ee0664eb5151c156080f69df2b
+  data.tar.gz: 4d2c0eb31572bfaad3d166e1f94500ba14d7f1d2732c81d94143e55e03e741adca3b55793771e2bd06cbc003940014276169f48c6ddb5863880ede2fcf167bef

data/CHANGELOG.adoc

@@ -2,6 +2,11 @@
 
 All notable changes to `asciidoctor-autoterm` are documented here.
 
+== 1.0.6 (2026-08-01)
+
+* Fixed: `antora-extension/index.js` adds a `nav.adoc` entry tagged `role=hidden` for each stub page. Required for the Assembler's merge to include the stub in the fused PDF document; the 1.0.5 extension omitted it, so a page `xref` to `terminology.adoc`/`index-page.adoc` never resolved to an in-document PDF link. See README.adoc
+* Fixed: `antora_processor.rb` finds the placeholder chapter `antora-extension/index.js` adds and mutates it in place into the real Terminology/Index section, instead of always appending a new one. Appending unconditionally left the placeholder as an empty, separately-ID'd chapter, so a correctly-resolved `xref` pointed at the empty placeholder, not the generated content. See README.adoc
+
 == 1.0.5 (2026-08-01)
 
 * Added: `antora-extension/index.js`, a companion Antora extension that registers publishable Terminology and Index stub pages so `xref` targets resolve. Published separately as `@baiyibai-asciidoctor/autoterm`; not shipped in the gem. See README.adoc

data/README.adoc

@@ -91,7 +91,9 @@ More information on using the Index with Antora Assembler is available at these
 
 == Antora HTML Site: Resolving `xref` Targets for Terminology and Index
 
-`@baiyibai-asciidoctor/autoterm` is an Antora Node.js extension that assists asciidoctor-pdf and antora-assembler: it registers publishable Terminology and Index stub pages so `xref` targets to them resolve.
+`@baiyibai-asciidoctor/autoterm` is an Antora Node.js extension that assists asciidoctor-pdf and antora-assembler.
+It registers publishable Terminology and Index stub pages, each with a `nav.adoc` entry tagged `role=hidden`, so `xref` targets to them resolve and the Assembler's merge includes them in the same document.
+Starting at 1.0.5, the gem's tree-processor finds each stub by its title and mutates it in place into the real section, instead of appending a duplicate.
 Wrap a source reference to either page in `ifdef::loader-assembler[]` and `endif::[]` so it renders only for the PDF build.
 
 [source,yaml]
@@ -101,3 +103,24 @@ antora:
     - require: '@baiyibai-asciidoctor/autoterm'
 ----
 
+[IMPORTANT]
+====
+`role=hidden` carries no built-in meaning for Antora or its default UI.
+A consuming UI bundle's nav template MUST skip rendering an item carrying that role, or the stub pages appear in the HTML site's navigation.
+For a Handlebars-based UI bundle derived from `@antora/ui-default`, wrap the item in `partials/nav-tree.hbs`:
+
+[source,hbs]
+----
+{{#unless (includes ./roles 'hidden')}}
+  <!-- existing <li> markup -->
+{{/unless}}
+----
+
+with an `includes` helper:
+
+[source,js]
+----
+module.exports = (arr, val) => Array.isArray(arr) && arr.includes(val)
+----
+====
+

data/lib/asciidoctor/autoterm/antora_processor.rb

@@ -1,14 +1,41 @@
 Asciidoctor::Extensions.register do
   tree_processor do
     process do |doc|
+      # A page xref to a real Antora page (xref:terminology.adoc[]) resolves to
+      # whatever section the Antora Assembler's rewriter computed for that page,
+      # not to a section this tree-processor creates fresh: the rewriter runs
+      # before this tree-processor, against a page that does not carry the real
+      # content yet. Creating a brand new section unconditionally, as this used
+      # to do, produces a second, differently-ID'd "Terminology"/"Index"
+      # section, leaving the fused page's own empty placeholder chapter in
+      # place with the ID any such xref actually resolves to.
+      #
+      # antora-extension/index.js registers that placeholder chapter (titled
+      # exactly "Terminology" / "Index") when include-terminology /
+      # include-index is set, so this tree-processor finds and mutates it in
+      # place instead of appending a new section, keeping it at the ID any
+      # page xref already resolved to. Standalone (non-Antora) usage, where no
+      # such placeholder exists, falls back to appending a new section as
+      # before.
       if doc.attributes['include-terminology'] == 'true'
-        if (last_section = doc.sections.last)
+        if (existing = doc.find_by(context: :section) { |s| s.level == 1 && s.title == 'Terminology' }.first)
+          existing.sectname = 'index'
+          existing.special = true
+          existing.set_attr 'type', 'terminology'
+          existing.set_attr 'sectnums', nil
+          existing.numbered = false
+        elsif (last_section = doc.sections.last)
           terminology_section = create_section last_section.parent, 'Terminology', { 'style' => 'index', 'type' => 'terminology' }, numbered: false
           terminology_section.parent << terminology_section
         end
       end
       if doc.attributes['include-index'] == 'true'
-        if (last_section = doc.sections.last)
+        if (existing = doc.find_by(context: :section) { |s| s.level == 1 && s.title == 'Index' }.first)
+          existing.sectname = 'index'
+          existing.special = true
+          existing.set_attr 'sectnums', nil
+          existing.numbered = false
+        elsif (last_section = doc.sections.last)
           index_section = create_section last_section.parent, 'Index', { 'style' => 'index' }, numbered: false
           index_section.parent << index_section
         end

data/lib/asciidoctor/autoterm/version.rb

@@ -1,5 +1,5 @@
 module Asciidoctor
   module Autoterm
-    VERSION = '1.0.5'
+    VERSION = '1.0.6'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-autoterm
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.0.6
 platform: ruby
 authors:
 - 白一百 baiyibai