@antora/assembler 1.0.0-beta.1 → 1.0.0-beta.11

package/adapters/asciidoctor/jsonl-logger.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+autoload :JSON, 'json'
+
+class JsonlFormatter < Asciidoctor::Logger::BasicFormatter
+  def call severity, time, progname, msg
+    entry = { 'time' => time.utc.to_i, 'level' => severity.downcase, 'name' => progname }
+    if ::String === msg
+      entry['msg'] = msg
+    else
+      loc = msg[:source_location]
+      entry['file'] = { 'path' => loc.file, 'line' => loc.lineno }
+      entry['msg'] = msg[:text]
+    end
+    (JSON.generate entry) + ?\n
+  end
+end
+
+proc do
+  logger = Asciidoctor::LoggerManager.logger
+  logger.formatter = JsonlFormatter.new
+  unless (progname = ::File.basename $PROGRAM_NAME).empty?
+    logger.progname = progname
+  end
+end.call

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 (buildConfig.command == null && typeof getDefaultCommand === 'function') {
+    buildConfig.command = await getDefaultCommand(buildConfig.cwd)
+  }
   const { publishSite: publishFiles = require('@antora/site-publisher') } = generatorFunctions
-  await prepareWorkspace(publishFiles, assemblyFiles, contentCatalog, buildConfig)
+  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()
@@ -85,7 +103,13 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
         }
         pages.forEach((fragment, page) => {
           const assemblerMeta = (page.assembler ??= {})
-          ;(assemblerMeta.exports ??= []).push({ fragment, file })
+          const exports = (assemblerMeta.exports ??= [])
+          const exportEntry = { fragment, file }
+          const insertIdx = exports.findIndex(
+            ({ file: candidate }) =>
+              !(candidate.src.component === page.src.component && candidate.src.version === page.src.version)
+          )
+          ~insertIdx ? exports.splice(insertIdx, 0, exportEntry) : exports.push(exportEntry)
           const extnameProp = extname.slice(1)
           if (extnameProp in assemblerMeta) return
           Object.defineProperty(assemblerMeta, extnameProp, {
@@ -99,24 +123,26 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
     })
 }
 
-function createResolveAssemblyModel (context, contentCatalog, defaults, intrinsicAttributes, navigationCatalog) {
+function createResolveAssemblyModel (context, contentCatalog, common, intrinsicAttributes, navigationCatalog) {
+  const logger = context.getLogger?.(PACKAGE_NAME)
   const { assemblerProfiles } = context.getVariables()
-  const { insertStartPage, rootLevel, sectionMergeStrategy } = defaults
   if (!assemblerProfiles) {
     return (componentVersion) => {
       const navigation =
         navigationCatalog?.getNavigation(componentVersion.name, componentVersion.version) ?? componentVersion.navigation
-      return { insertStartPage, rootLevel, sectionMergeStrategy, navigation }
+      return Object.assign({ logger }, common, { navigation })
     }
   }
-  const boundSendToLog = sendToLog.bind(context.getLogger ? context.getLogger(PACKAGE_NAME) : undefined)
+  const boundSendToLog = sendToLog.bind(logger)
   const { buildNavigation = require('@antora/navigation-builder') } = context.getFunctions()
   return (componentVersion) => {
     const componentVersionProfiles = assemblerProfiles.get(componentVersion.version + '@' + componentVersion.name)
-    const { navFiles, messages, ...model } = Object.assign(
-      { insertStartPage, rootLevel, sectionMergeStrategy },
-      componentVersionProfiles?.get(intrinsicAttributes['assembler-profile']) ?? componentVersionProfiles?.get()
-    )
+    const overrides =
+      componentVersionProfiles?.get(intrinsicAttributes['assembler-profile']) ?? componentVersionProfiles?.get() ?? {}
+    const { navFiles, messages } = overrides
+    const model = Object.assign({ logger }, common, overrides)
+    delete model.navFiles
+    delete model.messages
     const navigationOverride = navigationCatalog?.getNavigation(componentVersion.name, componentVersion.version)
     if (navigationOverride) return Object.assign(model, { navigation: navigationOverride })
     messages?.forEach(boundSendToLog)
@@ -143,7 +169,7 @@ function createResolveAssemblyModel (context, contentCatalog, defaults, intrinsi
   }
 }
 
-function prepareConvertAttributes (doc, targetExtname, buildConfig) {
+function prepareConvertAttributes (doc, targetExtname, relativeToOutput, buildConfig) {
   const {
     asciidoc: { attributes: docAttributes } = { attributes: {} },
     extname: docfilesuffix,
@@ -153,7 +179,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, {
@@ -162,7 +189,7 @@ function prepareConvertAttributes (doc, targetExtname, buildConfig) {
     docfilesuffix,
     'docname@': docname,
     imagesdir,
-    outdir: ospath.dirname(docfile),
+    outdir,
     outfile,
     outfilesuffix: targetExtname,
     toArgs (optionFlag, command) {
@@ -172,11 +199,15 @@ function prepareConvertAttributes (doc, targetExtname, buildConfig) {
         if (val) {
           val = `${name}=${padCharRef && typeof val.charAt === 'function' && val.charAt() === '&' ? ' ' : ''}${val}`
         } else if (val === '') {
+          if (name === 'asciidoctor-log-integration') {
+            args.push('-r', require.resolve('#asciidoctor-log-adapter'))
+            continue
+          }
           val = name
         } else {
           val = `!${name}${val === false ? '@' : ''}`
         }
-        args.push('-a', val)
+        args.push(optionFlag, val)
       }
       return args
     },
@@ -205,7 +236,7 @@ function findFirstExportWithExtname (extname) {
 }
 
 // TODO: if no workspace dir is defined, we shouldn't continue
-function prepareWorkspace (publishFiles, assemblyFiles, contentCatalog, buildConfig) {
+function prepareWorkspace (publishFiles, assemblyFiles, buildConfig) {
   const { dir, clean, keepSource } = buildConfig
   const files = []
   const outPaths = new Set()
@@ -220,9 +251,47 @@ function prepareWorkspace (publishFiles, assemblyFiles, contentCatalog, buildCon
   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 if ((match = /^asciidoctor: ([A-Z]+): (?:[^:]+: line (\d+): )?(.+)/.exec(line))) {
+          // NOTE we don't care about the filename in the message since it can only be docfile
+          const [, level, lineno, msg] = match
+          if (lineno) ctx.line = parseInt(lineno, 10)
+          logger[level === 'WARNING' ? 'warn' : level.toLowerCase()](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 p in obj) return true
+  for (const _ in obj) return true
   return false
 }
 

package/lib/configure.js

@@ -6,7 +6,8 @@ function configure (context, ...args) {
 
 function internalConfigure (converter, config = {}, providers = {}) {
   this.once('componentsRegistered', ({ contentCatalog, assemblerProfiles }) => {
-    this.updateVariables(assemblerProfiles ? undefined : { assemblerProfiles: getAssemblerProfiles(contentCatalog) })
+    if (assemblerProfiles) return
+    this.updateVariables({ assemblerProfiles: getAssemblerProfiles(contentCatalog) })
   })
 
   this.once('beforeProcess', ({ siteAsciiDocConfig }) => {
@@ -64,14 +65,10 @@ function getAssemblerProfiles (contentCatalog, assemblerProfiles = new Map()) {
 }
 
 function getAssemblerConfigFromDescriptor (descriptor = {}) {
-  let assemblerConfig = descriptor.ext?.assembler
+  const assemblerConfig = descriptor.ext?.assembler
   if (!assemblerConfig) return
-  if (Array.isArray(assemblerConfig)) {
-    if (!assemblerConfig.length) return
-  } else {
-    assemblerConfig = [assemblerConfig]
-  }
-  return assemblerConfig
+  if (!Array.isArray(assemblerConfig)) return [assemblerConfig]
+  if (assemblerConfig.length) return assemblerConfig
 }
 
 function initNavFile (file, component, version, index) {

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
@@ -16,7 +24,11 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') {
             () => false
           )
           .then((exists) =>
-            exists ? fsp.readFile(configSource).then((data) => camelCaseKeys(yaml.load(data), ['asciidoc'])) : {}
+            exists
+              ? fsp
+                  .readFile(configSource)
+                  .then((data) => Object.assign(camelCaseKeys(yaml.load(data), ['asciidoc']), { file: configSource }))
+              : {}
           )
   ).then((config) => {
     if (config.enabled === false) return undefined
@@ -42,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]
@@ -55,12 +67,19 @@ 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')
     }
     build.dir &&= expandPath(build.dir, { dot: playbook.dir })
-    build.cwd = playbook.dir // use playbook.dir for finding and loading require scripts
+    // used as cwd of command (and any scripts it requires)
+    build.cwd = build.cwd == null ? playbook.dir : expandPath(build.cwd, { dot: playbook.dir })
     if (!('clean' in build) && 'output' in playbook) build.clean = playbook.output.clean
     if (!('publish' in build)) build.publish = true
     if ('keepAggregateSource' in build) {
@@ -70,6 +89,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

@@ -1,6 +1,7 @@
 'use strict'
 
 const createAsciiDocFile = require('./util/create-asciidoc-file')
+const parseResourceRef = require('./util/parse-resource-ref')
 const path = require('node:path/posix')
 const sanitize = require('./util/sanitize')
 const unconvertInlineAsciiDoc = require('./util/unconvert-inline-asciidoc')
@@ -8,7 +9,7 @@ const unconvertInlineAsciiDoc = require('./util/unconvert-inline-asciidoc')
 const AttributeEntryRx = /^:([^:-][^:]*):(?: .*)?$/
 const BuiltInNamedEntities = { amp: '&', apos: "'", gt: '>', lt: '<', nbsp: ' ', quot: '"' }
 const CharRefRx = /&(?:([a-z][a-z]+\d{0,2})|#(?:(\d{2,6})|x([a-z\d]{2,5})));/g
-const DiscardAttributes = 'doctype leveloffset assembly-style underscore'.split(' ')
+const DiscardAttributes = 'doctype leveloffset assembly-navtitle assembly-style underscore'.split(' ')
 const ReservedIdNames = 'content header footnotes footer footer-text premable toc toctitle'.split(' ')
 
 function produceAssemblyFile (
@@ -24,11 +25,10 @@ function produceAssemblyFile (
   const pagesByUrl = files.reduce((map, it) => (it.src.family === 'page' ? map.set(it.pub.url, it) : map), new Map())
   if (outline.urlType === 'internal' && !pagesByUrl.get(outline.url) && !(outline.items || []).length) return
   const pagesInOutline = selectPagesInOutline(outline, pagesByUrl, componentVersion)
-  const navtitle = outline.content
   const buffer = mergeAsciiDoc(
     loadAsciiDoc,
     contentCatalog,
-    buildAsciiDocHeader(componentVersion, navtitle, assemblyModel),
+    buildAsciiDocHeader(componentVersion, outline.content, assemblyModel),
     componentVersion,
     outline,
     files,
@@ -38,7 +38,7 @@ function produceAssemblyFile (
     assemblyModel
   )
   const rootLevel = assemblyModel.rootLevel
-  const stem = rootLevel === 0 ? 'index' : generateSlug(navtitle)
+  const stem = rootLevel === 0 ? 'index' : generateSlug(buffer.navtitle)
   const downloadStem = [componentVersion.name, componentVersion.version, rootLevel === 0 ? '' : stem]
     .filter((it) => it)
     .join('-')
@@ -63,7 +63,7 @@ function buildAsciiDocHeader (componentVersion, navtitle, assemblyModel) {
   let doctitle = navtitleAsciiDoc
   if (navtitlePlain !== componentVersion.title) doctitle = `${componentVersion.title}: ${doctitle}`
   const version = componentVersion.version === 'master' ? '' : componentVersion.version
-  return [
+  const buffer = [
     `= ${doctitle}`,
     ...(version ? [`:revnumber: ${version}`] : []),
     ...(doctype === 'article' ? [] : [`:doctype: ${doctype ?? 'book'}`]),
@@ -75,16 +75,15 @@ function buildAsciiDocHeader (componentVersion, navtitle, assemblyModel) {
     `:page-component-display-version: ${componentVersion.displayVersion}`,
     `:page-component-title: ${componentVersion.title}`,
   ]
+  return Object.assign(buffer, { navtitle })
 }
 
 function selectPagesInOutline (outlineEntry, pagesByUrl, componentVersion, accum) {
   accum ??= Object.assign(new Map(), { assembled: { pages: new Map(), assets: new Set() } })
   const page = outlineEntry.urlType === 'internal' ? pagesByUrl.get(outlineEntry.url) : undefined
   if (page) {
-    if (page.src.component === componentVersion.name && page.src.version === componentVersion.version) {
-      accum.set(`${page.src.module === 'ROOT' ? '' : page.src.module + ':'}${page.src.relative}`, page)
-    }
-    accum.set(page.pub.url, page)
+    accum.set(createResourceKey(page.src), page)
+    accum.set(outlineEntry.url, page)
   }
   for (const item of outlineEntry.items || []) selectPagesInOutline(item, pagesByUrl, componentVersion, accum)
   return accum
@@ -106,39 +105,56 @@ function mergeAsciiDoc (
   supportsParts = false
 ) {
   // TODO: we could try to be smart about it and make sure the page with fragment is included at least once
-  if (outlineEntry.hash) return buffer
-  const { content: navtitle, items = [], unresolved, urlType, url } = outlineEntry
+  if (outlineEntry.hash) {
+    buffer.inBody ??= false
+    return buffer
+  }
+  let navtitle = outlineEntry.content
+  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 navtitlePlain = sanitize(navtitle)
-  const navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
-  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
-  // FIXME: ideally, resource ID would be stored in navigation so we can look up the page more efficiently
-  let page = urlType === 'internal' && !unresolved ? pagesInOutline.get(url) : undefined
-  if (page && pagesInOutline.assembled.pages.has(page)) page = undefined
-  if (page) {
-    let contents = page.src.contents
-    if (contents == null) return buffer
-    // NOTE: blank lines at top and bottom of document create mismatch when using line numbers to navigate source lines
-    // IMPORTANT: this must not leave behind lines the parser will drop!
-    // IDEA: another option is to capture initial lineno of reader and use as offset (but preseves those blank lines)
-    contents = Buffer.from(
-      contents
-        .toString()
-        .replace(/^(?:[ \t]*\r\n?|[ \t]*\n)+/, '')
-        .trimRight()
+  if (page && !pagesInOutline.assembled.pages.has(page)) {
+    const contents = page.src.contents
+    if (contents == null) {
+      buffer.inBody ??= false
+      return buffer
+    }
+    const { component, version, module: module_, relative, origin, mediaType } = page.src
+    const pageAsAsciiDoc = new page.constructor(
+      Object.assign({}, page, { contents: trimAsciiDoc(contents), mediaType })
     )
-    const { component, version, module: module_, relative, origin } = page.src
-    const topicPrefix = ~relative.indexOf('/') ? path.dirname(relative) + '/' : ''
-    const pageAsAsciiDoc = new page.constructor(Object.assign({}, page, { contents, mediaType: page.src.mediaType }))
     const doc = loadAsciiDoc(pageAsAsciiDoc, contentCatalog, asciidocConfig)
+    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
+        // 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()
       if (authors.length) {
@@ -153,18 +169,7 @@ function mergeAsciiDoc (
     }
     // NOTE: in Antora, docname is relative src path from module without file extension
     const docname = doc.getAttribute('docname')
-    const docnameForId = docname.replace(/[/.]/g, '-')
-    const qualifyId = component !== componentVersion.name
-    let idScope = docnameForId
-    let idPrefix
-    if (qualifyId) {
-      idScope = [component, module_ === 'ROOT' ? '' : module_, idScope].join(idCoordinateSeparator)
-    } else if (module_ !== 'ROOT') {
-      idScope = module_ + idCoordinateSeparator + idScope
-    } else if (ReservedIdNames.includes(docnameForId)) {
-      idScope = idPrefix = idScope + idScopeSeparator
-    }
-    idPrefix ??= idScope + idScopeSeparator
+    const { idPrefix, id: idScope } = generateId(page.src, componentVersion, idCoordinateSeparator, idScopeSeparator)
     let pageFragment = ''
     let pageRoles = ''
     let pageStyle = doc.getAttribute('assembly-style', '')
@@ -198,7 +203,6 @@ function mergeAsciiDoc (
     }
     buffer.push(`:page-module: ${module_}`)
     buffer.push(`:page-relative-src-path: ${relative}`)
-    //buffer.push(`:page-origin-type: ${origin.type}`)
     buffer.push(`:page-origin-url: ${origin.url}`)
     buffer.push(`:page-origin-start-path:${origin.startPath && ' '}${origin.startPath}`)
     buffer.push(`:page-origin-refname: ${origin.branch || origin.tag}`)
@@ -371,63 +375,59 @@ 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 pagePart, fragment, targetPage
+          let fragment, resource, resourceRef
           const hashIdx = target.indexOf('#')
           if (~hashIdx) {
-            pagePart = target.slice(0, hashIdx)
+            resourceRef = target.slice(0, hashIdx)
             fragment = target.slice(hashIdx + 1)
-            // TODO: for now, assume .adoc; in the future, consider other file extensions
-            if (pagePart && !pagePart.endsWith('.adoc')) pagePart += '.adoc'
-          } else if (target.endsWith('.adoc')) {
-            pagePart = target
+          } else if (target.endsWith('.adoc') || ~target.indexOf('$')) {
+            resourceRef = target
             fragment = ''
           } else {
             fragment = target
           }
-          if (!pagePart) {
-            // Q: should we validate the internal ID here?
-            return text && ~text.indexOf('=')
-              ? `xref:${idPrefix}${fragment}[${text}]`
-              : `<<${idPrefix}${fragment}${text ? ',' + text.replace(/\\]/g, ']') : ''}>>`
-          }
-          if (~pagePart.indexOf('@') || /:.*:/.test(pagePart)) {
-            if (siteUrl && (targetPage = contentCatalog.resolvePage(pagePart, page.src)) && targetPage.out) {
-              text ||= targetPage.asciidoc?.xreftext || target
-              return `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
+          // Q: should we validate the internal ID here?
+          if (!resourceRef) return `xref:${idPrefix}${fragment}[${text}]`
+          const resourceId = parseResourceRef(resourceRef, page.src, 'page', contentCatalog)
+          if (resourceId.family !== 'page') {
+            if (siteRoot && (resource = contentCatalog.getById(resourceId))?.pub) {
+              text ||= resource.asciidoc?.xreftext || target
+              return `${resolveLinkTarget(resource, siteRoot, pubRoot, linkRefStyle)}${fragment && '#' + fragment}[${text}]`
             }
-            // TODO: handle unresolved page better
+            // TODO: handle unresolved resource better
             return m
           }
-          let targetModule
-          const colonIdx = pagePart.indexOf(':')
-          if (~colonIdx) {
-            targetModule = pagePart.slice(0, colonIdx)
-            pagePart = pagePart.slice(colonIdx + 1)
-          } else {
-            targetModule = module_
-          }
-          if (pagePart.startsWith('./')) pagePart = topicPrefix + pagePart.slice(2)
-          const pageResourceRef = targetModule === 'ROOT' ? pagePart : `${targetModule}:${pagePart}`
-          if (!(targetPage = pagesInOutline.get(pageResourceRef))) {
-            if (siteUrl && (targetPage = contentCatalog.resolvePage(pageResourceRef, page.src)) && targetPage.out) {
-              text ||= targetPage.asciidoc?.xreftext || target
-              return `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
+          if (!(resource = pagesInOutline.get(createResourceKey(resourceId)))) {
+            if (siteRoot && (resource = contentCatalog.getById(resourceId))?.pub) {
+              text ||= resource.asciidoc?.xreftext || target
+              return `${resolveLinkTarget(resource, siteRoot, pubRoot, linkRefStyle)}${fragment && '#' + fragment}[${text}]`
             }
             // TODO: handle unresolved page better
             return m
           }
-          if (targetModule !== 'ROOT') pagePart = `${targetModule}${idCoordinateSeparator}${pagePart}`
-          pagePart = pagePart.replace(/\.adoc$/, '').replace(/[/.]/g, '-')
-          const refid = fragment
-            ? `${pagePart}${idScopeSeparator}${fragment}`
-            : pagePart + (ReservedIdNames.includes(pagePart) ? idScopeSeparator : '')
-          return `<<${refid}${text && text !== targetPage.title ? ',' + text.replace(/\\]/g, ']') : ''}>>`
+          if (fragment === resource.asciidoc.id) fragment = ''
+          if (
+            text &&
+            (assemblyModel.dropExplicitXrefText === 'always' ||
+              (assemblyModel.dropExplicitXrefText === 'if-redundant' && text === resource.title))
+          ) {
+            text = ''
+          }
+          const refid = generateId(
+            resource.src,
+            componentVersion,
+            idCoordinateSeparator,
+            idScopeSeparator,
+            text.length > 0,
+            fragment
+          ).id
+          return `xref:${refid}[${text}]`
         })
       }
       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,
@@ -436,7 +436,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::')) {
@@ -444,9 +444,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
@@ -500,10 +502,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]
@@ -542,6 +547,7 @@ function mergeAsciiDoc (
     }
   } else if (level) {
     if (atDocumentRoot && navtitlePlain === componentVersion.title) {
+      buffer.inBody ??= false
       level--
     } else {
       buffer.inBody = true
@@ -563,9 +569,16 @@ 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)) {
+            const refid = generateId(resource.src, componentVersion, idCoordinateSeparator, idScopeSeparator, true).id
+            sectionTitle = `xref:${refid}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+          } else if (siteRoot) {
+            sectionTitle = `${resolveLinkTarget(resource, siteRoot, pubRoot, linkRefStyle)}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+          }
+        }
       }
       let hlevel = level + 1
       if (hlevel > 6) {
@@ -621,12 +634,8 @@ function processDocumentHeader (doc, lines, buffer, ignoreLines) {
     }
     const line = lines[idx]
     if (open === ':' || open === '-:') {
-      if (line) {
-        if (open === ':') buffer.push(line)
-        if (!line.endsWith(' \\')) open = undefined
-      } else {
-        open = undefined
-      }
+      if (open === ':') buffer.push(line)
+      if (!line || !line.endsWith(' \\')) open = undefined
     } else if (line) {
       const chr0 = line.charAt()
       let attributeEntryMatch
@@ -642,7 +651,7 @@ function processDocumentHeader (doc, lines, buffer, ignoreLines) {
       } else if (chr0 === ':' && ~line.indexOf(':', 2) && (attributeEntryMatch = line.match(AttributeEntryRx))) {
         const attributeName = attributeEntryMatch[1].replace('!', '')
         if (DiscardAttributes.includes(attributeName)) {
-          if (line.endsWith(' \\')) open = '-:'
+          if (line.endsWith(' \\')) open = '-:' // disallow value continuation
         } else {
           if (line.endsWith(' \\')) open = ':'
           buffer.push(line)
@@ -650,6 +659,12 @@ function processDocumentHeader (doc, lines, buffer, ignoreLines) {
       } else if (belowDoctitle) {
         if (implicitLines.length === 2 || !/[\p{Alpha}0-9]/u.test(chr0)) break
         implicitLines.push(line)
+      } else if (chr0 === '[' && line.charAt(line.length - 1) === ']') {
+        const attrlist = line
+          .slice(1, -1)
+          .trim()
+          .replace(/(?:^\w[\w-]*(?!=|[\w-]))?([#.%]\w[\w-]*)*/, '')
+        if (attrlist) buffer.push('[' + attrlist + ']')
       }
     } else if (belowDoctitle) {
       break
@@ -672,7 +687,7 @@ function generateSlug (title) {
       return String.fromCharCode(dec ? parseInt(dec, 10) : parseInt(hex, 16))
     })
     .replace(/[\x27\u2019]/g, '')
-    .replace(/[^\p{Alpha}0-9\-]/gu, '-')
+    .replace(/[^\p{Alpha}0-9-]/gu, '-')
     .replace(/^-+|-+$|(-)-+/g, '$1')
 }
 
@@ -739,7 +754,19 @@ function isResourceSpec (str) {
 }
 
 function getObjectId (obj) {
-  return global.Opal.uid()
+  return global.Opal.id(obj)
+}
+
+// NOTE: blank lines at top and bottom of document create mismatch when using line numbers to navigate source lines
+// IMPORTANT: this must not leave behind lines the parser will drop!
+// IDEA: another option is to capture initial lineno of reader and use as offset (but preseves those blank lines)
+function trimAsciiDoc (buffer) {
+  return Buffer.from(
+    buffer
+      .toString()
+      .replace(/^(?:[ \t]*\r\n?|[ \t]*\n)+/, '')
+      .trimRight()
+  )
 }
 
 function safePush (onto, entries) {
@@ -752,4 +779,56 @@ 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
+}
+
+function createResourceKey ({ component, version, module: mod, family, relative }) {
+  return `${version}@${component}:${mod === 'ROOT' ? '' : mod}:${family === 'page' ? '' : family + '$'}${relative}`
+}
+
+function generateId (componentSrc, componentVersion, coordinateSep, scopeSep, escapePass, fragment) {
+  let { component, module: mod, relative } = componentSrc
+  let id = relative.replace(/\.adoc$/, '').replace(/[/.]/g, '-')
+  if (component !== componentVersion.name) {
+    id = [component, mod === 'ROOT' ? '' : mod, id].join(coordinateSep)
+  } else if (mod !== 'ROOT') {
+    if (escapePass && coordinateSep === ':' && /(?:pass|stem)$/.test(mod)) mod = mod.replace(/(?:pass|stem)$/, '\\$&')
+    id = mod + coordinateSep + id
+  } else if (ReservedIdNames.includes(id)) {
+    id += scopeSep
+    scopeSep = ''
+  }
+  const idPrefix = id + scopeSep
+  if (fragment) id = idPrefix + fragment
+  return { idPrefix, id }
+}
+
 module.exports = produceAssemblyFile

package/lib/produce-assembly-files.js

@@ -1,10 +1,12 @@
 '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')
 const selectMutableAttributes = require('./select-mutable-attributes')
 
+const ATTR_REF_RX = /\\?\{(\w[\w-]*)\}/g
 const IMAGE_MACRO_RX = /^image::?(.+?)\[(.*?)\]$/
 
 function produceAssemblyFiles (loadAsciiDoc, contentCatalog, assemblerConfig, resolveAssemblyModel) {
@@ -16,22 +18,55 @@ 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) => {
       const assemblyModel = resolveAssemblyModel(componentVersion)
       if (!assemblyModel.navigation) return accum
       const { name: componentName, version, title } = componentVersion
       const componentVersionAsciiDocConfig = getAsciiDocConfigWithAsciidoctorReducerExtension(componentVersion)
+      const mergedAsciiDocAttributes = collateAsciiDocAttributes(
+        Object.assign({ revdate }, componentVersionAsciiDocConfig.attributes),
+        assemblerAsciiDocAttributes,
+        { logger: assemblyModel.logger, mdc: configMdc }
+      )
       const mergedAsciiDocConfig = Object.assign({}, componentVersionAsciiDocConfig, {
-        attributes: Object.assign({ revdate }, componentVersionAsciiDocConfig.attributes, assemblerAsciiDocAttributes),
+        attributes: mergedAsciiDocAttributes,
       })
-      const mergedAsciiDocAttributes = mergedAsciiDocConfig.attributes
+      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)
@@ -87,7 +122,6 @@ function produceAssemblyFiles (loadAsciiDoc, contentCatalog, assemblerConfig, re
         accum.push(assemblyFile)
         return true
       }, false)
-      mergedAsciiDocAttributes.doctype = assemblyModel.doctype
       sourceHighlighter
         ? (mergedAsciiDocAttributes['source-highlighter'] = sourceHighlighter)
         : delete mergedAsciiDocAttributes['source-highlighter']
@@ -143,4 +177,39 @@ function prepareOutlines (navigation, rootEntry, rootLevel) {
   return items
 }
 
+function collateAsciiDocAttributes (collated, additional, { logger, mdc }) {
+  Object.entries(additional).forEach(([name, val]) => {
+    if (val && val.constructor === String) {
+      let alias
+      val = val.replace(ATTR_REF_RX, (ref, refname) => {
+        if (ref.charAt() === '\\') return ref.substr(1)
+        const refval = collated[refname]
+        if (refval == null || refval === false) {
+          if (refname in collated && ref === val) {
+            alias = refval
+          } else if (collated['attribute-missing'] === 'warn') {
+            if (logger) {
+              logger.warn(mdc, "Skipping reference to missing attribute '%s' in value of '%s' attribute", refname, name)
+            }
+          }
+          return ref
+        }
+        if (refval.constructor === String) return refval
+        if (ref !== val) return refval.toString()
+        alias = refval
+        return ref
+      })
+      if (alias !== undefined) val = alias
+    }
+    collated[name] = val
+  })
+  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,9 +3,9 @@
 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, ext: extname, name: stem } = path.parse(outRelative)
+  const { dir: dirname, base: basename } = path.parse(outRelative)
   const componentVersion = this.getComponentVersion(component, version)
   const versionSegment =
     'activeVersionSegment' in componentVersion
@@ -48,7 +48,7 @@ function resolveActiveVersionSegment (component, version) {
     this.removeFile((startPage = this.addFile({ src: startPageSrc })))
   }
   const outPathSegments = startPage.out.path.split('/')
-  for (const depth of startPage.out.moduleRootPath.split('/')) outPathSegments.pop()
+  for (const _ of startPage.out.moduleRootPath.split('/')) outPathSegments.pop()
   if (startPageSrc.module !== 'ROOT') outPathSegments.pop()
   if (startPageSrc.component !== 'ROOT') outPathSegments.shift()
   return outPathSegments.length ? outPathSegments[0] : ''

package/lib/util/create-asciidoc-file.js

@@ -1,7 +1,6 @@
 'use strict'
 
 const computeOut = require('./compute-out')
-const { posix: path } = require('node:path')
 
 function createAsciiDocFile (contentCatalog, file) {
   file.mediaType = 'text/asciidoc'

package/lib/util/parse-resource-ref.js

@@ -0,0 +1,36 @@
+'use strict'
+
+function parseResourceRef (ref, ctx = {}, family = undefined, contentCatalog = undefined) {
+  const atIdx = ref.indexOf('@')
+  let firstColonIdx = ref.indexOf(':')
+  let component, version, module_
+  if (~atIdx && (~firstColonIdx ? atIdx < firstColonIdx : true)) {
+    if ((version = ref.slice(0, atIdx)) === '_') version = ''
+    ref = ref.slice(atIdx + 1)
+    if (~firstColonIdx) firstColonIdx -= atIdx + 1
+  }
+  const addColons = ~firstColonIdx ? (~ref.indexOf(':', firstColonIdx + 1) ? '' : ':') : '::'
+  const segments = (addColons + ref).split(':')
+  if ((component = segments[0])) {
+    module_ = segments[1] || 'ROOT'
+    version ??= contentCatalog?.getComponent(component)?.latest.version
+  } else {
+    component = ctx.component
+    version ??= ctx.version
+    module_ = segments[1] || ctx.module || 'ROOT'
+  }
+  let relative = segments.length > 3 ? segments.slice(2).join(':') : segments[2]
+  const dollarIdx = relative.indexOf('$')
+  if (~dollarIdx) {
+    family = relative.slice(0, dollarIdx) || family
+    relative = relative.slice(dollarIdx + 1)
+  }
+  if (relative.charAt() === '.' && relative.charAt(1) === '/') {
+    const ctxRelative = ctx.relative
+    const topic = ctxRelative ? ctxRelative.slice(0, (ctxRelative.lastIndexOf('/') + 1 || 1) - 1) : undefined
+    relative = (topic ? topic + '/' : '') + relative.slice(2)
+  }
+  return { component, version, module: module_, family, relative }
+}
+
+module.exports = parseResourceRef

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/assembler",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.11",
   "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)",
@@ -27,11 +27,13 @@
     ".": "./lib/index.js",
     "./filter-component-versions": "./lib/filter-component-versions.js",
     "./load-config": "./lib/load-config.js",
+    "./parse-resource-ref": "./lib/util/parse-resource-ref.js",
     "./produce-assembly-file": "./lib/produce-assembly-file.js",
     "./produce-assembly-files": "./lib/produce-assembly-files.js",
     "./select-mutable-attributes": "./lib/select-mutable-attributes.js"
   },
   "imports": {
+    "#asciidoctor-log-adapter": "./adapters/asciidoctor/jsonl-logger.rb",
     "#run-command": "@antora/run-command-helper",
     "#unconvert-inline-asciidoc": "./lib/util/unconvert-inline-asciidoc.js"
   },
@@ -51,6 +53,7 @@
     "node": ">=16.0.0"
   },
   "files": [
+    "adapters/",
     "lib/"
   ],
   "keywords": [