From ed2cad13dfbc8e491f8fdb7f01adc22c28704bcb Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Thu, 25 Sep 2025 16:53:05 -0600 Subject: [PATCH] resolves #25 introduce drop_explicit_xref_text key to control when Assembler drops text of xref --- CHANGELOG.adoc | 1 + .../ROOT/pages/configure-assembly.adoc | 27 +++++++++++++++++++ packages/assembler/lib/load-config.js | 13 ++++++++- .../assembler/lib/produce-assembly-file.js | 9 ++++++- .../assembler/lib/produce-assembly-files.js | 1 + .../test/produce-assembly-files-test.js | 18 +++++++++++++ .../scenarios/rewrite-page-links/data.yml | 2 +- .../rewrite-page-links/expects/index.adoc | 2 +- 8 files changed, 69 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index df99064..80ead5d 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -13,6 +13,7 @@ For a detailed view of what's changed, refer to the {url-repo}/commits[commit hi * introduce `embedReferenceStyle` property on exporter's converter object to control how image targets are rewritten (when embedded or bundled) (#100) * introduce `link_reference_style` subkey on the `assembly` category key in the Assembler configuration to control how linkable targets are rewritten (#116) * assign intrinsic attributes assembler-filetype and assembler-filetype- (#122) +* introduce `drop_explicit_xref_text` subkey on the `assembly` category key to control when Assembler drops the text of an xref (#25) === Changed diff --git a/docs/assembler/modules/ROOT/pages/configure-assembly.adoc b/docs/assembler/modules/ROOT/pages/configure-assembly.adoc index 91e2747..c26ef34 100644 --- a/docs/assembler/modules/ROOT/pages/configure-assembly.adoc +++ b/docs/assembler/modules/ROOT/pages/configure-assembly.adoc @@ -50,6 +50,11 @@ Acceptable keys and their default values are listed in the table below. |absolute, root-relative, relative |Controls how Assembler rewrites references to linkable resources. +|<> +|never +|always, if-redundant, never +|Controls when Assembler drops the text of an xref. + |<> | |String @@ -433,6 +438,28 @@ One exception is when the export is HTML and the value of the key is `relative`. When exporting to HTML, this key is also used to control how image references are rewritten. When exporting to any other format, the converter controls this behavior. +[#drop-explicit-xref-text-key] +== drop_explicit_xref_text + +The `drop_explicit_xref_text` key controls whether Assembler drops the explicit text defined on xrefs (almost always page references). + +The `drop_explicit_xref_text` key is an optional key that can be set in [.path]_antora-assembler.yml_. +It accepts the values `always`, `if-redundant`, and `never`. +The default value is `never`. + +.antora-assembler.yml +[,yaml] +---- +assembly: + drop_explicit_xref_text: if-redundant +---- + +The benefit of dropping the explicit text is that once in the assembly, the xref's text can be controlled by the global `xrefstyle` attribute. +For example, when linking to a section with numbering enabled, the rendered text will look like `Section 2.3, “Installation”` if the `xreftext` is set to full. +If the original xref text were to be preserved, that text would be used as entered. + +The `if-redundant` setting only drops the text in the case that the explicit text matches the title of the target page. + [#profile-key] == profile diff --git a/packages/assembler/lib/load-config.js b/packages/assembler/lib/load-config.js index c3a2d1f..5198dd1 100644 --- a/packages/assembler/lib/load-config.js +++ b/packages/assembler/lib/load-config.js @@ -5,6 +5,14 @@ const fsp = require('node:fs/promises') const os = require('node:os') const yaml = require('js-yaml') +const ASSEMBLY_KEYS = [ + 'rootLevel', + 'insertStartPage', + 'sectionMergeStrategy', + 'linkReferenceStyle', + 'dropExplicitXrefText', +] + function loadConfig (playbook, configSource = './antora-assembler.yml') { return ( configSource.constructor === Object @@ -46,7 +54,7 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') { const remapAssemblyKeys = !('assembly' in config) const assembly = (config.assembly ??= {}) if (remapAssemblyKeys) { - for (const key of ['rootLevel', 'insertStartPage', 'sectionMergeStrategy', 'linkReferenceStyle']) { + for (const key of ASSEMBLY_KEYS) { if (!(key in config)) continue assembly[key] = config[key] delete config[key] @@ -62,6 +70,9 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') { if (['relative', 'root-relative', 'absolute'].indexOf(assembly.linkReferenceStyle) < 0) { assembly.linkReferenceStyle = 'absolute' } + if (['always', 'if-redundant', 'never'].indexOf(assembly.dropExplicitXrefText) < 0) { + assembly.dropExplicitXrefText = 'never' + } const build = (config.build ??= {}) if (build.dir === '$' + '{playbook.output.dir}') { throw new Error('Not implemented') diff --git a/packages/assembler/lib/produce-assembly-file.js b/packages/assembler/lib/produce-assembly-file.js index 6c4e601..5380e74 100644 --- a/packages/assembler/lib/produce-assembly-file.js +++ b/packages/assembler/lib/produce-assembly-file.js @@ -447,7 +447,14 @@ function mergeAsciiDoc ( const refid = fragment ? `${relativePart}${idScopeSeparator}${fragment}` : relativePart + (ReservedIdNames.includes(relativePart) ? idScopeSeparator : '') - return `<<${refid}${text && text !== resource.title ? ',' + text.replace(/\\]/g, ']') : ''}>>` + if ( + text && + (assemblyModel.dropExplicitXrefText === 'always' || + (assemblyModel.dropExplicitXrefText === 'if-redundant' && text === resource.title)) + ) { + text = '' + } + return `<<${refid}${text ? ',' + text.replace(/\\]/g, ']') : ''}>>` }) } if (~line.indexOf('link:{attachmentsdir}/')) { diff --git a/packages/assembler/lib/produce-assembly-files.js b/packages/assembler/lib/produce-assembly-files.js index 2d1a249..68e88c6 100644 --- a/packages/assembler/lib/produce-assembly-files.js +++ b/packages/assembler/lib/produce-assembly-files.js @@ -20,6 +20,7 @@ function produceAssemblyFiles (loadAsciiDoc, contentCatalog, assemblerConfig, re xmlIds: assemblyConfig.xmlIds, embedReferenceStyle: assemblyConfig.embedReferenceStyle, linkReferenceStyle: assemblyConfig.linkReferenceStyle, + dropExplicitXrefText: assemblyConfig.dropExplicitXrefText, }) const assemblerAsciiDocAttributes = Object.assign({}, assemblerAsciiDocConfig.attributes) const { revdate, 'source-highlighter': sourceHighlighter } = assemblerAsciiDocAttributes diff --git a/packages/assembler/test/produce-assembly-files-test.js b/packages/assembler/test/produce-assembly-files-test.js index 7d019a8..2f17c70 100644 --- a/packages/assembler/test/produce-assembly-files-test.js +++ b/packages/assembler/test/produce-assembly-files-test.js @@ -183,6 +183,24 @@ describe('produceAssemblyFiles()', () => { await runScenario('rewrite-relative-page-links', __dirname) }) + it('should drop redundant page link text when drop_explicit_xref_text is if-redundant', async () => { + const { loadAsciiDoc, contentCatalog, assemblerConfig } = await loadScenario('rewrite-page-links', __dirname) + assemblerConfig.assembly.dropExplicitXrefText = 'if-redundant' + const assemblyFiles = await produceAssemblyFiles(loadAsciiDoc, contentCatalog, assemblerConfig) + assert.equal(assemblyFiles.length, 1) + const actual = assemblyFiles[0].contents.toString() + assert.match(actual, /<>/) + }) + + it('should drop redundant page link text when drop_explicit_xref_text is always', async () => { + const { loadAsciiDoc, contentCatalog, assemblerConfig } = await loadScenario('rewrite-page-links', __dirname) + assemblerConfig.assembly.dropExplicitXrefText = 'always' + const assemblyFiles = await produceAssemblyFiles(loadAsciiDoc, contentCatalog, assemblerConfig) + assert.equal(assemblyFiles.length, 1) + const actual = assemblyFiles[0].contents.toString() + assert.match(actual, /<>/) + }) + it('should allow generated IDs to be XML compliant', async () => { await runScenario('xml-ids', __dirname) }) diff --git a/packages/assembler/test/scenarios/rewrite-page-links/data.yml b/packages/assembler/test/scenarios/rewrite-page-links/data.yml index 89afd99..25aae86 100644 --- a/packages/assembler/test/scenarios/rewrite-page-links/data.yml +++ b/packages/assembler/test/scenarios/rewrite-page-links/data.yml @@ -18,7 +18,7 @@ files: You are on xref:the-page.adoc[this page]. - This page follows the xref:header.adoc[]. + This page follows the xref:header.adoc[Header]. Also see xref:other-module:the-page.adoc[]. diff --git a/packages/assembler/test/scenarios/rewrite-page-links/expects/index.adoc b/packages/assembler/test/scenarios/rewrite-page-links/expects/index.adoc index f434cd2..452612f 100644 --- a/packages/assembler/test/scenarios/rewrite-page-links/expects/index.adoc +++ b/packages/assembler/test/scenarios/rewrite-page-links/expects/index.adoc @@ -34,7 +34,7 @@ Stuff at the top. You are on <>. -This page follows the <>. +This page follows the <>. Also see <>. -- GitLab