From 0bfc06b24be7038537e3df1604460d5d843793ca Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Mon, 13 Oct 2025 18:08:25 -0600 Subject: [PATCH] resolves #124 preserve xref syntax from source document to ensure it's parsed properly --- CHANGELOG.adoc | 6 ++++++ packages/assembler/lib/produce-assembly-file.js | 12 ++++-------- .../assembler/test/produce-assembly-files-test.js | 4 ++-- .../scenarios/cross-component/expects/index.adoc | 2 +- .../ignore-duplicate-nav-entry/expects/index.adoc | 2 +- .../scenarios/insert-start-page/expects/index.adoc | 2 +- .../expects/index.adoc | 2 +- .../test/scenarios/rewrite-page-links/data.yml | 2 ++ .../scenarios/rewrite-page-links/expects/index.adoc | 8 +++++--- .../rewrite-relative-page-links/expects/index.adoc | 8 ++++---- .../test/scenarios/scrub-ids/expects/index.adoc | 2 +- .../skip-commented-lines/expects/index.adoc | 2 +- .../test/scenarios/xml-ids/expects/index.adoc | 2 +- 13 files changed, 30 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 1f4a6a2..d0cc9b6 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -4,6 +4,12 @@ This document provides a summary of all notable changes to Antora Assembler by release. For a detailed view of what's changed, refer to the {url-repo}/commits[commit history] of this project. +== Unreleased + +=== Fixed + +* preserve xref syntax from source document to ensure text and (where applicable) attributes are parsed propertly (#124) + == 1.0.0-beta.8 (2025-09-30) === Fixed diff --git a/packages/assembler/lib/produce-assembly-file.js b/packages/assembler/lib/produce-assembly-file.js index 5380e74..e8dafac 100644 --- a/packages/assembler/lib/produce-assembly-file.js +++ b/packages/assembler/lib/produce-assembly-file.js @@ -400,12 +400,8 @@ function mergeAsciiDoc ( } else { fragment = target } - if (!relativePart) { - // Q: should we validate the internal ID here? - return text && ~text.indexOf('=') - ? `xref:${idPrefix}${fragment}[${text}]` - : `<<${idPrefix}${fragment}${text ? ',' + text.replace(/\\]/g, ']') : ''}>>` - } + // Q: should we validate the internal ID here? + if (!relativePart) return `xref:${idPrefix}${fragment}[${text}]` if (~dollarIdx) { if (relativePart.slice(dollarIdx).startsWith('$./')) { relativePart = relativePart.slice(0, dollarIdx + 1) + topicPrefix + relativePart.slice(dollarIdx + 3) @@ -454,7 +450,7 @@ function mergeAsciiDoc ( ) { text = '' } - return `<<${refid}${text ? ',' + text.replace(/\\]/g, ']') : ''}>>` + return `xref:${refid}[${text}]` }) } if (~line.indexOf('link:{attachmentsdir}/')) { @@ -609,7 +605,7 @@ function mergeAsciiDoc ( let refid = resource.src.relative.replace(/\.adoc$/, '').replace(/[/.]/g, '-') if (refid.startsWith('./')) refid = topicPrefix + refid.slice(2) if (resource.src.module !== 'ROOT') refid = `${resource.src.module}${idCoordinateSeparator}${refid}` - sectionTitle = `<<${refid},${navtitleAsciiDoc}>>` + sectionTitle = `xref:${refid}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]` } else if (siteRoot) { sectionTitle = `${resolveLinkTarget(resource, siteRoot, pubRoot, linkRefStyle)}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]` } diff --git a/packages/assembler/test/produce-assembly-files-test.js b/packages/assembler/test/produce-assembly-files-test.js index 2f17c70..4e6094f 100644 --- a/packages/assembler/test/produce-assembly-files-test.js +++ b/packages/assembler/test/produce-assembly-files-test.js @@ -189,7 +189,7 @@ describe('produceAssemblyFiles()', () => { const assemblyFiles = await produceAssemblyFiles(loadAsciiDoc, contentCatalog, assemblerConfig) assert.equal(assemblyFiles.length, 1) const actual = assemblyFiles[0].contents.toString() - assert.match(actual, /<>/) + assert.match(actual, /xref:header:::\[\]/) }) it('should drop redundant page link text when drop_explicit_xref_text is always', async () => { @@ -198,7 +198,7 @@ describe('produceAssemblyFiles()', () => { const assemblyFiles = await produceAssemblyFiles(loadAsciiDoc, contentCatalog, assemblerConfig) assert.equal(assemblyFiles.length, 1) const actual = assemblyFiles[0].contents.toString() - assert.match(actual, /<>/) + assert.match(actual, /xref:the-page\[\]/) }) it('should allow generated IDs to be XML compliant', async () => { diff --git a/packages/assembler/test/scenarios/cross-component/expects/index.adoc b/packages/assembler/test/scenarios/cross-component/expects/index.adoc index d556221..d6b64f2 100644 --- a/packages/assembler/test/scenarios/cross-component/expects/index.adoc +++ b/packages/assembler/test/scenarios/cross-component/expects/index.adoc @@ -21,7 +21,7 @@ contents -see <> +see xref:another-page[] :docname: another-page :page-component-name: other-component diff --git a/packages/assembler/test/scenarios/ignore-duplicate-nav-entry/expects/index.adoc b/packages/assembler/test/scenarios/ignore-duplicate-nav-entry/expects/index.adoc index c0d0417..b695e5c 100644 --- a/packages/assembler/test/scenarios/ignore-duplicate-nav-entry/expects/index.adoc +++ b/packages/assembler/test/scenarios/ignore-duplicate-nav-entry/expects/index.adoc @@ -48,5 +48,5 @@ contents contents :!sectids: -=== <> +=== xref:the-page[The Page Title] :sectids: diff --git a/packages/assembler/test/scenarios/insert-start-page/expects/index.adoc b/packages/assembler/test/scenarios/insert-start-page/expects/index.adoc index 526666f..d166e11 100644 --- a/packages/assembler/test/scenarios/insert-start-page/expects/index.adoc +++ b/packages/assembler/test/scenarios/insert-start-page/expects/index.adoc @@ -33,4 +33,4 @@ contents contents -back to <> +back to xref:overview[] diff --git a/packages/assembler/test/scenarios/rewrite-internal-xref-macro-targets/expects/index.adoc b/packages/assembler/test/scenarios/rewrite-internal-xref-macro-targets/expects/index.adoc index 1377119..b986b9c 100644 --- a/packages/assembler/test/scenarios/rewrite-internal-xref-macro-targets/expects/index.adoc +++ b/packages/assembler/test/scenarios/rewrite-internal-xref-macro-targets/expects/index.adoc @@ -19,7 +19,7 @@ [#the-page] == The Page Title -You'll find <> in <>. +You'll find xref:the-page:::_table_id[] in xref:the-page:::_section_title[]. [discrete#the-page:::_section_title] === Section Title diff --git a/packages/assembler/test/scenarios/rewrite-page-links/data.yml b/packages/assembler/test/scenarios/rewrite-page-links/data.yml index 25aae86..6985ee0 100644 --- a/packages/assembler/test/scenarios/rewrite-page-links/data.yml +++ b/packages/assembler/test/scenarios/rewrite-page-links/data.yml @@ -25,6 +25,8 @@ files: Go back to the site to see xref:other-component::index.adoc[] and xref:imported-component::index.adoc[Imported Page]. You won't be able to see xref:_unpublished.adoc[] since it is not published. + + You have reached the end of xref:the-page.adoc[xrefstyle=full]. - relative: the-page.adoc module: other-module contents: |- 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 452612f..fabd2c7 100644 --- a/packages/assembler/test/scenarios/rewrite-page-links/expects/index.adoc +++ b/packages/assembler/test/scenarios/rewrite-page-links/expects/index.adoc @@ -32,16 +32,18 @@ Stuff at the top. [#the-page] == The Page -You are on <>. +You are on xref:the-page[this page]. -This page follows the <>. +This page follows the xref:header:::[Header]. -Also see <>. +Also see xref:other-module:the-page[]. Go back to the site to see https://preview-docs.example.org/other-component/index.html[Another Page] and https://docs.example.org/imported-component/index.html[Imported Page]. You won't be able to see xref:_unpublished.adoc[] since it is not published. +You have reached the end of xref:the-page[xrefstyle=full]. + :docname: the-page :page-module: other-module :page-relative-src-path: the-page.adoc diff --git a/packages/assembler/test/scenarios/rewrite-relative-page-links/expects/index.adoc b/packages/assembler/test/scenarios/rewrite-relative-page-links/expects/index.adoc index 39c3df2..b150978 100644 --- a/packages/assembler/test/scenarios/rewrite-relative-page-links/expects/index.adoc +++ b/packages/assembler/test/scenarios/rewrite-relative-page-links/expects/index.adoc @@ -19,9 +19,9 @@ [#the-page] == The Page -You are on <>. +You are on xref:the-page[this page]. -Also see <>. +Also see xref:other-module:the-topic-the-page[]. :docname: the-topic/the-page :page-module: other-module @@ -36,7 +36,7 @@ Also see <>. content -Also see <>. +Also see xref:other-module:the-topic-other-page[the other page]. :docname: the-topic/other-page :page-module: other-module @@ -51,7 +51,7 @@ Also see <>. content -Also see <>. +Also see xref:another-module:the-topic-another-page[another other page]. :docname: the-topic/another-page :page-module: another-module diff --git a/packages/assembler/test/scenarios/scrub-ids/expects/index.adoc b/packages/assembler/test/scenarios/scrub-ids/expects/index.adoc index 1290f31..6b67869 100644 --- a/packages/assembler/test/scenarios/scrub-ids/expects/index.adoc +++ b/packages/assembler/test/scenarios/scrub-ids/expects/index.adoc @@ -19,7 +19,7 @@ [#the-page] == The Page -Refer to <>. +Refer to xref:subfolder-upgrade-from-7-1:::section-name[Section Name]. :docname: subfolder/upgrade-from-7.1 :page-module: ROOT diff --git a/packages/assembler/test/scenarios/skip-commented-lines/expects/index.adoc b/packages/assembler/test/scenarios/skip-commented-lines/expects/index.adoc index 16442fc..a5688e6 100644 --- a/packages/assembler/test/scenarios/skip-commented-lines/expects/index.adoc +++ b/packages/assembler/test/scenarios/skip-commented-lines/expects/index.adoc @@ -24,7 +24,7 @@ //// Also ignore xref:the-component:other-module:the-page.adoc[]. //// -See <>. +See xref:other-module:the-page[]. :docname: the-page :page-module: other-module diff --git a/packages/assembler/test/scenarios/xml-ids/expects/index.adoc b/packages/assembler/test/scenarios/xml-ids/expects/index.adoc index 360a1c0..ac244e4 100644 --- a/packages/assembler/test/scenarios/xml-ids/expects/index.adoc +++ b/packages/assembler/test/scenarios/xml-ids/expects/index.adoc @@ -22,7 +22,7 @@ [discrete#the-page---the-section] === The Section -Also see <> in <>. +Also see xref:other-module----the-page---the-section[The Section] in xref:other-module----the-page[]. :docname: the-page :page-module: other-module -- GitLab