@antora/assembler 1.0.0-beta.5 → 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, 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()
@@ -99,23 +117,24 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
     })
 }
 
-function createResolveAssemblyModel (context, contentCatalog, shared, intrinsicAttributes, navigationCatalog) {
+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({}, shared, { 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 overrides =
       componentVersionProfiles?.get(intrinsicAttributes['assembler-profile']) ?? componentVersionProfiles?.get() ?? {}
     const { navFiles, messages } = overrides
-    const model = Object.assign({}, shared, overrides)
+    const model = Object.assign({ logger }, common, overrides)
     delete model.navFiles
     delete model.messages
     const navigationOverride = navigationCatalog?.getNavigation(componentVersion.name, componentVersion.version)
@@ -144,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,
@@ -154,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, {
@@ -163,7 +183,7 @@ function prepareConvertAttributes (doc, targetExtname, buildConfig) {
     docfilesuffix,
     'docname@': docname,
     imagesdir,
-    outdir: ospath.dirname(docfile),
+    outdir,
     outfile,
     outfilesuffix: targetExtname,
     toArgs (optionFlag, command) {
@@ -177,7 +197,7 @@ function prepareConvertAttributes (doc, targetExtname, buildConfig) {
         } else {
           val = `!${name}${val === false ? '@' : ''}`
         }
-        args.push('-a', val)
+        args.push(optionFlag, val)
       }
       return args
     },
@@ -206,7 +226,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()
@@ -221,9 +241,42 @@ 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 {
+          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/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,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')
@@ -70,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

@@ -8,7 +8,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 +24,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 +37,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 +62,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,6 +74,7 @@ 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) {
@@ -106,39 +106,57 @@ 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()
-    )
-    const { component, version, module: module_, relative, origin } = page.src
+  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 topicPrefix = ~relative.indexOf('/') ? path.dirname(relative) + '/' : ''
-    const pageAsAsciiDoc = new page.constructor(Object.assign({}, page, { contents, mediaType: page.src.mediaType }))
+    const pageAsAsciiDoc = new page.constructor(
+      Object.assign({}, page, { contents: trimAsciiDoc(contents), 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) {
@@ -198,7 +216,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,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) {
@@ -400,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}${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
@@ -417,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
@@ -434,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,
@@ -449,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::')) {
@@ -457,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
@@ -513,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]
@@ -555,6 +580,7 @@ function mergeAsciiDoc (
     }
   } else if (level) {
     if (atDocumentRoot && navtitlePlain === componentVersion.title) {
+      buffer.inBody ??= false
       level--
     } else {
       buffer.inBody = true
@@ -576,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) {
@@ -663,6 +698,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
@@ -685,7 +726,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')
 }
 
@@ -752,7 +793,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) {
@@ -765,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,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)
@@ -142,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/assembler",
-  "version": "1.0.0-beta.5",
+  "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)",