From eca2d0f21dc41bbe27a88bcd775f6fbe848f0748 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Sat, 22 Nov 2025 23:23:48 -0700 Subject: [PATCH] resolves #134 allow assembly.link_reference_style to be relative when export filetype is pdf --- CHANGELOG.adoc | 6 ++++++ docs/assembler/modules/ROOT/pages/configure-assembly.adoc | 6 ++++++ packages/assembler/lib/produce-assembly-files.js | 2 +- 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index afd6196..89642f2 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 f622354..858dace 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 68e88c6..44678a3 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() -- GitLab