diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 1f4a6a2a03852201f5331b7918d0ff08608bf7f1..d0cc9b66d1508164e08b03d0e667b18b56dee3ca 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 5380e7485a1eb993d1f70b7b7628ee40d75542f2..e8dafac1f91b5d6f433c13d610e1bfe786a4334d 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 2f17c702883efaafc1b5b87c225b44655781aebf..4e6094fd44c1efa48f554ca14d35f64ea7cc4128 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, /<<header:::>>/)
+    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, /<<the-page>>/)
+    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 d556221604435e373bbb9763243a4cea099a97a0..d6b64f2b47f287401cb8bad1bea25473278ba1f4 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 <<another-page>>
+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 c0d0417fa5b68805195845881fafa116ce6424e6..b695e5ccd676fd3f4488393c9dad724bc817ae4e 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:
-=== <<the-page,The Page Title>>
+=== 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 526666fcb9179167616544675f7a38d7c489d248..d166e11500fb9960c49883d3db255589059b9e9a 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 <<overview>>
+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 13771199d25cffb5074e76caccaf6bdf37fd2fad..b986b9c3f178f690db7efab5cd14e0db70703c27 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 <<the-page:::_table_id>> in <<the-page:::_section_title>>.
+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 25aae86c469713fdfded7af472d0878818ad14db..6985ee02ec730f6e1799427bdcfc7f4a8c59b69a 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 452612f19733464cd82b324a8b0f28a47b00f1c7..fabd2c761d7910cab061e24086fe152fcc5c10d6 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 <<the-page,this page>>.
+You are on xref:the-page[this page].
 
-This page follows the <<header:::,Header>>.
+This page follows the xref:header:::[Header].
 
-Also see <<other-module:the-page>>.
+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 39c3df235515a18e3b7c8f5c256880df2d247741..b1509789f99b991bcafbb3cdc9010ce2e655a85e 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 <<the-page,this page>>.
+You are on xref:the-page[this page].
 
-Also see <<other-module:the-topic-the-page>>.
+Also see xref:other-module:the-topic-the-page[].
 
 :docname: the-topic/the-page
 :page-module: other-module
@@ -36,7 +36,7 @@ Also see <<other-module:the-topic-the-page>>.
 
 content
 
-Also see <<other-module:the-topic-other-page,the other page>>.
+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 <<other-module:the-topic-other-page,the other page>>.
 
 content
 
-Also see <<another-module:the-topic-another-page,another other page>>.
+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 1290f31ed95fb79213fecd1dc990084af5819e3c..6b678694241c78ed1e3513dad3802c73cde7e1d3 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 <<subfolder-upgrade-from-7-1:::section-name,Section Name>>.
+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 16442fc39188ab483a022473b215c5f2c84734a9..a5688e640349589d5bf1c455ae3ad20575e3efee 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 <<other-module:the-page>>.
+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 360a1c05b62d1cca9d76d280e0db3d84fe012910..ac244e498f132e9c39dd06b4500dd641d0e5e477 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 <<other-module----the-page---the-section,The Section>> in <<other-module----the-page>>.
+Also see xref:other-module----the-page---the-section[The Section] in xref:other-module----the-page[].
 
 :docname: the-page
 :page-module: other-module