diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index afd6196ef603665182b9df63bc816ebf0bf3b630..89642f28288c70b3b437ef0dba1353acf4b9be60 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 + +=== Changed + +* Allow assembly.link_reference_style to be relative when export filetype is pdf (#134) + == 1.0.0-beta.13 (2025-10-25) === Fixed diff --git a/docs/assembler/modules/ROOT/pages/configure-assembly.adoc b/docs/assembler/modules/ROOT/pages/configure-assembly.adoc index f6223544fb6ff63949f24a660fd57cde6fb17b04..858dace8059b9b6188bd4e8a2410e0c14533cdd4 100644 --- a/docs/assembler/modules/ROOT/pages/configure-assembly.adoc +++ b/docs/assembler/modules/ROOT/pages/configure-assembly.adoc @@ -415,6 +415,7 @@ The `link_reference_style` key controls how Assembler rewrites references to lin The `link_reference_style` key is an optional key that can be set in [.path]_antora-assembler.yml_. When exporting to HTML, it accepts the values `absolute`, `root-relative`, and `relative`. +When exporting to PDF, it accepts the values `absolute` and `relative`. When exporting to any other format, it only accepts the value `absolute`. The default value is `absolute`. @@ -435,6 +436,11 @@ This allows the HTML export to be relocated to another location on the same host When the value is `relative`, the references are rewritten using a relative path starting from the export file. This allows the HTML export to seamlessly integrate with pages and other resources in the site without coupling the reference to the site URL. +IMPORTANT: In order to successfully use the `relative` value when exporting to PDF, the PDF must be viewed from within the site on a local filesystem. +Otherwise, the references will not be satisfied. +Use this combination with care. +When possible, the value `absolute` should be preferred. + In order for the functionality used by this key to work properly, the site URL must be set. One exception is when the export is HTML and the value of the key is `relative`. diff --git a/packages/assembler/lib/produce-assembly-files.js b/packages/assembler/lib/produce-assembly-files.js index 68e88c62abe643d0d2fd60481256b7802ef46fef..44678a36091afc6b38bf804f0083a9a324ddbc63 100644 --- a/packages/assembler/lib/produce-assembly-files.js +++ b/packages/assembler/lib/produce-assembly-files.js @@ -64,7 +64,7 @@ function produceAssemblyFiles (loadAsciiDoc, contentCatalog, assemblerConfig, re if (linkRefStyle === 'absolute' && siteRoot?.url == null) linkRefStyle = 'root-relative' if (linkRefStyle === 'root-relative' && siteRoot?.path == null) linkRefStyle = 'relative' assemblyModel.linkReferenceStyle = linkRefStyle - } else { + } else if (assemblyModel.filetype !== 'pdf') { assemblyModel.linkReferenceStyle = 'absolute' } const auxiliaryImages = new Set()