@antora/assembler 1.0.0-beta.6 → 1.0.0-beta.7

package/lib/assemble-content.js

@@ -13,6 +13,7 @@ const { stringify: toJSON } = JSON
 
 const invariably = { new: () => ({}), void: () => undefined }
 const PACKAGE_NAME = require('../package.json').name
+const NEWLINE_RX = /(?:\r?\n)+/
 
 async function assembleContent (playbook, contentCatalog, converter, { configSource, navigationCatalog }) {
   const assemblerConfig = await loadConfig(playbook, configSource)
@@ -26,10 +27,20 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
       }
   const generatorFunctions = context.getFunctions()
   const { loadAsciiDoc = require('@antora/asciidoc-loader') } = generatorFunctions
-  const targetBackend = converter == null ? undefined : (converter.backend ?? converter.extname?.slice(1))
+  const {
+    convert = converter,
+    getDefaultCommand,
+    extname: targetExtname = '',
+    backend: targetBackend = targetExtname.slice(1),
+    embedReferenceStyle = 'relative',
+    mediaType: targetMediaType,
+    loggerName = PACKAGE_NAME,
+  } = converter ?? {}
   const { assembly: assemblyConfig, build: buildConfig } = assemblerConfig
+  assemblyConfig.embedReferenceStyle = embedReferenceStyle
   const { profile = targetBackend } = assemblyConfig
   const intrinsicAttributes = { 'loader-assembler': '' }
+  buildConfig.cwd ??= process.cwd()
   if (profile) {
     buildConfig.dir ??= ospath.join(playbook.dir ?? process.cwd(), `build/assembler-${profile}`)
     intrinsicAttributes[`assembler-profile-${profile}`] = ''
@@ -41,6 +52,11 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
   } else {
     buildConfig.dir ??= ospath.join(playbook.dir ?? process.cwd(), 'build/assembler')
   }
+  if (targetExtname) {
+    const targetFiletype = targetExtname.slice(1)
+    intrinsicAttributes[`assembler-filetype-${targetFiletype}`] = ''
+    intrinsicAttributes['assembler-filetype'] = targetFiletype
+  }
   Object.assign(assemblerConfig.asciidoc.attributes, intrinsicAttributes)
   const assemblyFiles = produceAssemblyFiles(
     loadAsciiDoc,
@@ -48,21 +64,23 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
     assemblerConfig,
     createResolveAssemblyModel(context, contentCatalog, assemblyConfig, intrinsicAttributes, navigationCatalog)
   )
-  const { convert = converter, extname: targetExtname, mediaType: targetMediaType } = converter ?? {}
-  if (!(convert && assemblyFiles.length)) return assemblyFiles
+  if (!(assemblyFiles.length && typeof convert === 'function')) return assemblyFiles
+  if (typeof getDefaultCommand === 'function') {
+    buildConfig.command = await getDefaultCommand(buildConfig.cwd)
+  }
   const { publishSite: publishFiles = require('@antora/site-publisher') } = generatorFunctions
   await prepareWorkspace(publishFiles, assemblyFiles, buildConfig)
   const boundConvert = convert.bind(context)
   return new PromiseQueue({ concurrency: buildConfig.processLimit })
     .add(
       assemblyFiles.map((doc) => async () => {
-        const convertAttributes = prepareConvertAttributes(doc, targetExtname, buildConfig)
+        const relativeToOutput = embedReferenceStyle === 'output-relative'
+        const convertAttributes = prepareConvertAttributes(doc, targetExtname, relativeToOutput, buildConfig)
         if (buildConfig.mkdirs) await fsp.mkdir(convertAttributes.outdir, { recursive: true, force: true })
-        return boundConvert(doc, convertAttributes, buildConfig).then(
-          (fileOrContents = new LazyReadable(() => fs.createReadStream(convertAttributes.outfile))) => {
-            return coerceToExportFormat(doc, targetBackend, targetExtname, targetMediaType, fileOrContents)
-          }
-        )
+        return boundConvert(doc, convertAttributes, buildConfig).then((result) => {
+          const fileOrContents = resolveFileOrContents.call(context, result, convertAttributes, buildConfig, loggerName)
+          return coerceToExportFormat(doc, targetBackend, targetExtname, targetMediaType, fileOrContents)
+        })
       })
     )
     .toPromise()
@@ -99,14 +117,14 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
     })
 }
 
-function createResolveAssemblyModel (context, contentCatalog, shared, intrinsicAttributes, navigationCatalog) {
-  const logger = context.getLogger ? context.getLogger(PACKAGE_NAME) : undefined
+function createResolveAssemblyModel (context, contentCatalog, common, intrinsicAttributes, navigationCatalog) {
+  const logger = context.getLogger?.(PACKAGE_NAME)
   const { assemblerProfiles } = context.getVariables()
   if (!assemblerProfiles) {
     return (componentVersion) => {
       const navigation =
         navigationCatalog?.getNavigation(componentVersion.name, componentVersion.version) ?? componentVersion.navigation
-      return Object.assign({ logger }, shared, { navigation })
+      return Object.assign({ logger }, common, { navigation })
     }
   }
   const boundSendToLog = sendToLog.bind(logger)
@@ -116,7 +134,7 @@ function createResolveAssemblyModel (context, contentCatalog, shared, intrinsicA
     const overrides =
       componentVersionProfiles?.get(intrinsicAttributes['assembler-profile']) ?? componentVersionProfiles?.get() ?? {}
     const { navFiles, messages } = overrides
-    const model = Object.assign({ logger }, shared, overrides)
+    const model = Object.assign({ logger }, common, overrides)
     delete model.navFiles
     delete model.messages
     const navigationOverride = navigationCatalog?.getNavigation(componentVersion.name, componentVersion.version)
@@ -145,7 +163,7 @@ function createResolveAssemblyModel (context, contentCatalog, shared, intrinsicA
   }
 }
 
-function prepareConvertAttributes (doc, targetExtname, buildConfig) {
+function prepareConvertAttributes (doc, targetExtname, relativeToOutput, buildConfig) {
   const {
     asciidoc: { attributes: docAttributes } = { attributes: {} },
     extname: docfilesuffix,
@@ -155,7 +173,8 @@ function prepareConvertAttributes (doc, targetExtname, buildConfig) {
   const { cwd = process.cwd(), dir = cwd } = buildConfig
   const docname = family + '$' + relative.slice(0, relative.length - docfilesuffix.length)
   const docfile = ospath.join(dir, reldocfile)
-  const docdir = dir
+  const outdir = ospath.dirname(docfile)
+  const docdir = relativeToOutput ? dir : outdir
   const imagesdir = ''
   const outfile = docfile.slice(0, docfile.length - docfilesuffix.length) + targetExtname
   const attributes = Object.assign({}, docAttributes, {
@@ -164,7 +183,7 @@ function prepareConvertAttributes (doc, targetExtname, buildConfig) {
     docfilesuffix,
     'docname@': docname,
     imagesdir,
-    outdir: ospath.dirname(docfile),
+    outdir,
     outfile,
     outfilesuffix: targetExtname,
     toArgs (optionFlag, command) {
@@ -222,6 +241,39 @@ function prepareWorkspace (publishFiles, assemblyFiles, buildConfig) {
   return publishFiles({ output: { clean, dir } }, { getFiles: () => files })
 }
 
+function resolveFileOrContents (convertResult, convertAttributes, buildConfig, loggerName) {
+  let fileOrContents
+  if (convertResult?.status != null) {
+    fileOrContents = 'file' in convertResult ? convertResult.file : convertResult.contents
+    let logger, match
+    if (buildConfig.stderrSink === 'log' && convertResult.stderr.length && (logger = this.getLogger(loggerName))) {
+      const docfile = convertAttributes.docfile
+      const command = buildConfig.command
+      const stderr = convertResult.stderr.toString().trimEnd()
+      stderr.split(NEWLINE_RX).forEach((line) => {
+        const ctx = { command, file: { path: docfile } }
+        if (line.charAt() === '{' && line.charAt(line.length - 1) === '}') {
+          const entry = JSON.parse(line)
+          if (entry.name) ctx.program = entry.name
+          if (entry.file?.line) ctx.line = entry.file.line
+          logger[entry.level](ctx, entry.msg)
+        } else if ((match = /^(.+):(\d+): warning: (.+)/.exec(line))) {
+          const [, scriptPath, lineno, msg] = match
+          ctx.stack = [{ file: { path: scriptPath }, line: parseInt(lineno, 10) }]
+          logger.warn(ctx, msg)
+        } else {
+          logger.info(ctx, line)
+        }
+      })
+    }
+  } else if (convertResult !== undefined) {
+    return convertResult
+  }
+  return fileOrContents === undefined
+    ? new LazyReadable(() => fs.createReadStream(convertAttributes.outfile))
+    : fileOrContents
+}
+
 function isBound (obj) {
   if (obj == null) return false
   for (const _ in obj) return true

package/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']) {
+      for (const key of ASSEMBLY_KEYS) {
         if (!(key in config)) continue
         assembly[key] = config[key]
         delete config[key]
@@ -59,6 +67,12 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') {
     if (['discrete', 'fuse', 'enclose'].indexOf(assembly.sectionMergeStrategy) < 0) {
       assembly.sectionMergeStrategy = 'discrete'
     }
+    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')
@@ -74,6 +88,14 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') {
     if (!build.processLimit) {
       build.processLimit = 'processLimit' in build ? Infinity : Math.round(os.cpus().length * 0.5)
     }
+    if ('stderr' in build) {
+      if (build.stderr === 'log') {
+        build.stderr = 'buffer'
+        build.stderrSink = 'log'
+      } else if (!['ignore', 'print'].includes(build.stderr)) {
+        delete build.stderr
+      }
+    }
     return config
   })
 }

package/lib/produce-assembly-file.js

@@ -114,16 +114,22 @@ function mergeAsciiDoc (
   let navtitlePlain = sanitize(navtitle)
   let navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
   const { items = [], unresolved, urlType, url } = outlineEntry
+  const {
+    doctype,
+    filetype,
+    embedReferenceStyle: embedRefStyle,
+    linkReferenceStyle: linkRefStyle,
+    outDirname,
+    siteRoot,
+    xmlIds,
+  } = assemblyModel
   // FIXME: ideally, resource ID would be stored in navigation so we can look up the page more efficiently
   const page = urlType === 'internal' && !unresolved ? pagesInOutline.get(url) : undefined
   const atDocumentRoot = !buffer.inBody
-  const atBookRoot = atDocumentRoot && !level && assemblyModel.doctype === 'book' && (supportsParts = true)
+  const atBookRoot = atDocumentRoot && !level && doctype === 'book' && (supportsParts = true)
   const hasItems = items.length > 0
-  const siteUrl = ((val) => {
-    if (!val || val === '/') return ''
-    return val.charAt(val.length - 1) === '/' ? val.slice(0, val.length - 1) : val
-  })(asciidocConfig.attributes['primary-site-url'] || asciidocConfig.attributes['site-url'])
-  const idSeparator = assemblyModel.xmlIds ? '-' : ':'
+  const pubRoot = outDirname ? '/' + outDirname : ''
+  const idSeparator = xmlIds ? '-' : ':'
   const idScopeSeparator = idSeparator.repeat(3)
   const idCoordinateSeparator = idSeparator === '-' ? '----' : idSeparator
   if (page && !pagesInOutline.assembled.pages.has(page)) {
@@ -141,7 +147,15 @@ function mergeAsciiDoc (
     if (doc.hasAttribute('assembly-navtitle')) {
       navtitleAsciiDoc = doc.getAttribute('assembly-navtitle')
       navtitlePlain = sanitize((navtitle = doc.$apply_reftext_subs(navtitleAsciiDoc)))
-      if (buffer.inBody == null) buffer.navtitle = navtitle
+      if (buffer.inBody == null) {
+        buffer.navtitle = navtitle
+        // Q do we need to assert !level here?
+        if (assemblyModel.rootLevel) {
+          let doctitle = navtitleAsciiDoc
+          if (navtitlePlain !== componentVersion.title) doctitle = `${componentVersion.title}: ${doctitle}`
+          buffer[0] = `= ${doctitle}`
+        }
+      }
     }
     if (atDocumentRoot) {
       const authors = doc.getAuthors()
@@ -374,7 +388,7 @@ function mergeAsciiDoc (
       if (~line.indexOf('xref:')) {
         // Q: should we allow : as first character of target?
         line = line.replace(/(?<![\\+])xref:((?:\.\/)?[\p{Alpha}0-9_/.{#].*?)\[(|.*?[^\\])\]/gu, (m, target, text) => {
-          let relativePart, fragment, targetResource, isPage
+          let relativePart, fragment, resource, isPage
           const hashIdx = target.indexOf('#')
           const dollarIdx = target.indexOf('$')
           if (~hashIdx) {
@@ -403,9 +417,9 @@ function mergeAsciiDoc (
             if (~hashIdx && !relativePart.endsWith('.adoc')) relativePart += '.adoc'
           }
           if (!isPage || ~relativePart.indexOf('@') || /:.*:/.test(relativePart)) {
-            if (siteUrl && (targetResource = contentCatalog.resolveResource(relativePart, page.src, 'page'))?.pub) {
-              text ||= targetResource.asciidoc?.xreftext || target
-              return `${siteUrl}${targetResource.pub.url.replace(/_/g, '{underscore}')}${fragment && '#' + fragment}[${text}]`
+            if (siteRoot && (resource = contentCatalog.resolveResource(relativePart, page.src, 'page'))?.pub) {
+              text ||= resource.asciidoc?.xreftext || target
+              return `${resolveLinkTarget(resource, siteRoot, pubRoot, linkRefStyle)}${fragment && '#' + fragment}[${text}]`
             }
             // TODO: handle unresolved resource better
             return m
@@ -420,14 +434,10 @@ function mergeAsciiDoc (
             targetModule = module_
           }
           const pageResourceRef = targetModule === 'ROOT' ? relativePart : `${targetModule}:${relativePart}`
-          if (!(targetResource = pagesInOutline.get(pageResourceRef))) {
-            if (
-              siteUrl &&
-              (targetResource = contentCatalog.resolvePage(pageResourceRef, page.src)) &&
-              targetResource.out
-            ) {
-              text ||= targetResource.asciidoc?.xreftext || target
-              return `${siteUrl}${targetResource.pub.url}${fragment && '#' + fragment}[${text}]`
+          if (!(resource = pagesInOutline.get(pageResourceRef))) {
+            if (siteRoot && (resource = contentCatalog.resolvePage(pageResourceRef, page.src)) && resource.out) {
+              text ||= resource.asciidoc?.xreftext || target
+              return `${resolveLinkTarget(resource, siteRoot, pubRoot, linkRefStyle)}${fragment && '#' + fragment}[${text}]`
             }
             // TODO: handle unresolved page better
             return m
@@ -437,13 +447,20 @@ function mergeAsciiDoc (
           const refid = fragment
             ? `${relativePart}${idScopeSeparator}${fragment}`
             : relativePart + (ReservedIdNames.includes(relativePart) ? idScopeSeparator : '')
-          return `<<${refid}${text && text !== targetResource.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}/')) {
         line = line.replace(/(?<![\\+])link:\{attachmentsdir\}\/([^\s[]+)\[(|.*?[^\\])\]/g, (m, relative, text) => {
           const attachment =
-            siteUrl &&
+            siteRoot &&
             contentCatalog.getById({
               component: componentVersion.name,
               version: componentVersion.version,
@@ -452,7 +469,7 @@ function mergeAsciiDoc (
               relative,
             })
           // TODO: handle unresolved attachment page
-          return attachment?.out ? `${siteUrl}${attachment.pub.url.replace(/_/g, '{underscore}')}[${text}]` : m
+          return attachment?.out ? `${resolveLinkTarget(attachment, siteRoot, pubRoot, linkRefStyle)}[${text}]` : m
         })
       }
       if (~line.indexOf('image:') && !line.startsWith('image::')) {
@@ -460,9 +477,11 @@ function mergeAsciiDoc (
           if (isResourceSpec(target)) {
             const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
             // TODO: handle (or report) unresolved image better
-            if (image?.out) {
+            if (image?.out && (filetype !== 'html' || siteRoot)) {
               pagesInOutline.assembled.assets.add(image)
-              return `image:${image.out.path.replace(/_/g, '{underscore}')}[${attrlist}]`
+              return filetype === 'html'
+                ? `image:${resolveLinkTarget(image, siteRoot, pubRoot, linkRefStyle)}[${attrlist}]`
+                : `image:${resolveEmbedTarget(image, outDirname, embedRefStyle, true)}[${attrlist}]`
             }
           }
           return m
@@ -516,10 +535,13 @@ function mergeAsciiDoc (
             if (isResourceSpec(target)) {
               const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
               // FIXME: handle (or report) case when image is not resolved
-              if (image?.out) {
-                const boxedAttrlist = line.slice(line.indexOf('['))
+              if (image?.out && (filetype !== 'html' || siteRoot)) {
+                const attrlist = line.slice(line.indexOf('[') + 1, -1)
                 pagesInOutline.assembled.assets.add(image)
-                lines[idx] = `${prefix}image::${image.out.path}${boxedAttrlist}`
+                lines[idx] =
+                  filetype === 'html'
+                    ? `${prefix}image::${resolveLinkTarget(image, siteRoot, pubRoot, linkRefStyle, false)}[${attrlist}]`
+                    : `${prefix}image::${resolveEmbedTarget(image, outDirname, embedRefStyle)}[${attrlist}]`
               }
             }
             lastImageMacroAt = [idx, imageMacroOffset]
@@ -580,9 +602,18 @@ function mergeAsciiDoc (
       let sectionTitle = navtitleAsciiDoc
       if (urlType === 'external') {
         sectionTitle = `${url}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
-      } else if (urlType === 'internal' && !unresolved && siteUrl) {
+      } else if (urlType === 'internal' && !unresolved) {
         const resource = files.find((it) => it.pub.url === url)
-        if (resource) sectionTitle = `${siteUrl}${resource.pub.url}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+        if (resource) {
+          if (resource.src.family === 'page' && pagesInOutline.has(resource.pub.url)) {
+            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}>>`
+          } else if (siteRoot) {
+            sectionTitle = `${resolveLinkTarget(resource, siteRoot, pubRoot, linkRefStyle)}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+          }
+        }
       }
       let hlevel = level + 1
       if (hlevel > 6) {
@@ -787,4 +818,35 @@ function safePush (onto, entries) {
   }
 }
 
+function resolveEmbedTarget (resource, outDirname, referenceStyle, escapeForInline) {
+  const target =
+    referenceStyle === 'output-relative' ? resource.out.path : path.relative(outDirname + '/', resource.out.path)
+  return escapeForInline ? target.replace(/_/g, '{underscore}') : target
+}
+
+function resolveLinkTarget (resource, siteRoot, pubRoot, referenceStyle, escapeForInline = true) {
+  let target
+  if (resource.site?.url) {
+    target = ['', resource.pub.url]
+  } else {
+    switch (referenceStyle) {
+      case 'absolute':
+        target = ['', siteRoot.url + resource.pub.url]
+        break
+      case 'root-relative':
+        target = ['link:', siteRoot.path + resource.pub.url]
+        break
+      default:
+        target = ['link:', computeRelativeUrl(pubRoot + '/', resource.pub.url)]
+    }
+  }
+  if (escapeForInline) target[1] = target[1].replace(/_/g, '{underscore}')
+  return target.join('')
+}
+
+function computeRelativeUrl (from, to) {
+  const rel = path.relative(from, to)
+  return to.charAt(to.length - 1) === '/' ? rel + '/' : rel
+}
+
 module.exports = produceAssemblyFile

package/lib/produce-assembly-files.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const computeOut = require('./util/compute-out')
 const createAsciiDocFile = require('./util/create-asciidoc-file')
 const filterComponentVersions = require('./filter-component-versions')
 const produceAssemblyFile = require('./produce-assembly-file')
@@ -17,12 +18,16 @@ function produceAssemblyFiles (loadAsciiDoc, contentCatalog, assemblerConfig, re
     sectionMergeStrategy: assemblyConfig.sectionMergeStrategy,
     navigation: componentVersion.navigation,
     xmlIds: assemblyConfig.xmlIds,
+    embedReferenceStyle: assemblyConfig.embedReferenceStyle,
+    linkReferenceStyle: assemblyConfig.linkReferenceStyle,
+    dropExplicitXrefText: assemblyConfig.dropExplicitXrefText,
   })
   const assemblerAsciiDocAttributes = Object.assign({}, assemblerAsciiDocConfig.attributes)
   const { revdate, 'source-highlighter': sourceHighlighter } = assemblerAsciiDocAttributes
   delete assemblerAsciiDocAttributes.revdate
   delete assemblerAsciiDocAttributes['source-highlighter']
   const publishableFiles = contentCatalog.getFiles().filter((file) => file.out)
+  let siteRoot
   const configMdc = assemblerConfig.file ? { file: { path: assemblerConfig.file } } : {}
   return filterComponentVersions(contentCatalog.getComponents(), assemblerConfig.componentVersionFilter.names).reduce(
     (accum, componentVersion) => {
@@ -38,6 +43,30 @@ function produceAssemblyFiles (loadAsciiDoc, contentCatalog, assemblerConfig, re
       const mergedAsciiDocConfig = Object.assign({}, componentVersionAsciiDocConfig, {
         attributes: mergedAsciiDocAttributes,
       })
+      assemblyModel.outDirname = computeOut.call(contentCatalog, {
+        component: componentName,
+        version,
+        family: 'export',
+        relative: '.index.adoc',
+      }).dirname
+      assemblyModel.filetype = assemblerAsciiDocAttributes['assembler-filetype']
+      assemblyModel.siteRoot =
+        siteRoot === undefined
+          ? (siteRoot ??= ((val) => {
+              if (!val) return null
+              if (val.charAt(val.length - 1) === '/') val = val.slice(0, val.length - 1)
+              if (!val || val.charAt() === '/') return { path: val }
+              return { url: val, path: extractUrlPath(val) }
+            })(mergedAsciiDocAttributes['site-url'] || mergedAsciiDocAttributes['primary-site-url']))
+          : siteRoot
+      if (assemblyModel.filetype === 'html') {
+        let linkRefStyle = assemblyModel.linkReferenceStyle
+        if (linkRefStyle === 'absolute' && siteRoot?.url == null) linkRefStyle = 'root-relative'
+        if (linkRefStyle === 'root-relative' && siteRoot?.path == null) linkRefStyle = 'relative'
+        assemblyModel.linkReferenceStyle = linkRefStyle
+      } else {
+        assemblyModel.linkReferenceStyle = 'absolute'
+      }
       const auxiliaryImages = new Set()
       Object.entries(mergedAsciiDocAttributes).forEach(([name, val]) => {
         const match = name.endsWith('-image') && val.startsWith('image:') && IMAGE_MACRO_RX.exec(val)
@@ -177,4 +206,10 @@ function collateAsciiDocAttributes (collated, additional, { logger, mdc }) {
   return collated
 }
 
+function extractUrlPath (url) {
+  if (!url) return ''
+  const urlPath = new URL(url).pathname
+  return urlPath === '/' ? '' : urlPath
+}
+
 module.exports = produceAssemblyFiles

package/lib/util/compute-out.js

@@ -3,7 +3,7 @@
 const { posix: path } = require('node:path')
 
 function computeOut (src) {
-  const { component, version, module: module_, family, relative } = src
+  const { component, version, module: module_ = 'ROOT', family, relative } = src
   const outRelative = family === 'page' ? relative.replace(/\.adoc$/, '.html') : relative
   const { dir: dirname, base: basename } = path.parse(outRelative)
   const componentVersion = this.getComponentVersion(component, version)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/assembler",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.7",
   "description": "A JavaScript library that merges AsciiDoc content from multiple pages in an Antora site into assembly files and delegates to an exporter to convert those files to another format, such as PDF.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",