@antora/assembler 1.0.0-alpha.7 → 1.0.0-alpha.9

package/lib/assemble-content.js

@@ -3,8 +3,9 @@
 const loadConfig = require('./load-config')
 const produceAggregateDocuments = require('./produce-aggregate-documents')
 const PromiseQueue = require('./util/promise-queue')
+const runCommand = require('./util/run-command')
 
-async function assembleContent (playbook, contentCatalog, converter, { siteCatalog, configSource }) {
+async function assembleContent (playbook, contentCatalog, convertDocument, { siteCatalog, configSource }) {
   // Q: could we get ContentCatalog#getComponentVersionStartPage() in Antora core?
   if (typeof contentCatalog.getComponentVersionStartPage !== 'function') {
     contentCatalog.getComponentVersionStartPage = function (component, version) {
@@ -16,14 +17,14 @@ async function assembleContent (playbook, contentCatalog, converter, { siteCatal
   const generatorFunctions = this ? this.getFunctions() : {}
   const { loadAsciiDoc = require('@antora/asciidoc-loader') } = generatorFunctions
   const aggregateDocuments = produceAggregateDocuments(loadAsciiDoc, contentCatalog, assemblerConfig)
-  if (!converter) return aggregateDocuments
+  if (!convertDocument) return aggregateDocuments
   const { publishSite: publishFiles = require('@antora/site-publisher') } = generatorFunctions
   const buildConfig = assemblerConfig.build
   await prepareWorkspace(publishFiles, aggregateDocuments, contentCatalog, buildConfig)
-  // TODO: pass more information to converter so it doesn't have to compute internal stuff
+  // TODO: pass more information to convertDocument so it doesn't have to compute internal stuff
   // Q: don't we need to pass in the combined/resolved AsciiDoc attributes per file or component version?
   return new PromiseQueue({ concurrency: buildConfig.processLimit })
-    .add(aggregateDocuments.map((doc) => () => converter.call(this, doc, buildConfig)))
+    .add(aggregateDocuments.map((doc) => () => convertDocument.call(this, doc, buildConfig, runCommand)))
     .toPromise()
     .then((files) => {
       if (buildConfig.publish && siteCatalog) siteCatalog.addFiles(files)

package/lib/filter-component-versions.js

@@ -21,11 +21,11 @@ function compilePatterns (patterns) {
   if (patterns[0].charAt() === '!') patterns = ['**', ...patterns]
   return patterns.map((pattern) => {
     const negated = pattern.charAt() === '!'
-    if (negated) pattern = pattern.substr(1)
+    if (negated) pattern = pattern.slice(1)
     let version
     const separatorIdx = pattern.search(VERSION_SEPARATOR_RX)
     if (~separatorIdx) {
-      pattern = (version = true) && `${pattern.substr(0, separatorIdx)}%${pattern.substr(separatorIdx + 1) || '*'}`
+      pattern = (version = true) && `${pattern.slice(0, separatorIdx)}%${pattern.slice(separatorIdx + 1) || '*'}`
     }
     return Object.assign(makePicomatchRx(pattern, PICOMATCH_OPTS), {
       globstar: pattern === '**',

package/lib/load-config.js

@@ -29,6 +29,7 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') {
     if (!('doctype' in asciidocAttrs)) asciidocAttrs.doctype = 'book'
     if (!('revdate' in asciidocAttrs)) asciidocAttrs.revdate = getLocalDate()
     asciidocAttrs['page-partial'] = null
+    asciidocAttrs['loader-assembler'] = ''
     if (config.componentVersions == null) {
       config.componentVersions = ['*']
     } else if (typeof config.componentVersions === 'string') {
@@ -46,7 +47,7 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') {
     } else {
       build.dir = expandPath(build.dir || './build/assembler', { dot: playbook.dir })
     }
-    build.cwd = playbook.dir // use playbook.dir the purpose of finding and loading require scripts
+    build.cwd = playbook.dir // use playbook.dir for the purpose of finding and loading require scripts
     if (!('clean' in build) && 'output' in playbook) build.clean = playbook.output.clean
     if (!('publish' in build)) build.publish = true
     if (!build.processLimit) {
@@ -62,7 +63,7 @@ function camelCaseKeys (o, stopPaths = [], p) {
   const pathPrefix = p ? p + '.' : ''
   const accum = {}
   for (const [k, v] of Object.entries(o)) {
-    const camelKey = k.charAt() + k.substr(1).replace(/_([a-z])/g, (_, l) => l.toUpperCase())
+    const camelKey = k.charAt() + k.slice(1).replace(/_([a-z])/g, (_, l) => l.toUpperCase())
     accum[camelKey] = ~stopPaths.indexOf(pathPrefix + camelKey) ? v : camelCaseKeys(v, stopPaths, pathPrefix + camelKey)
   }
   return accum

package/lib/produce-aggregate-document.js

@@ -2,6 +2,8 @@
 
 const File = require('vinyl')
 const path = require('node:path/posix')
+const sanitize = require('./util/sanitize')
+const unconvertInlineAsciiDoc = require('./util/unconvert-inline-asciidoc')
 
 function produceAggregateDocument (
   loadAsciiDoc,
@@ -14,12 +16,20 @@ function produceAggregateDocument (
   mutableAttributes,
   sectionMergeStrategy = 'discrete'
 ) {
-  const pagesInOutline = selectPagesInOutline(
-    outline,
-    pages.filter((it) => it.out)
-  )
+  const pagesInOutline = selectPagesInOutline(outline, pages)
   const navtitle = outline.content
-  const stem = generateStem(componentVersion, navtitle)
+  const templateFile = contentCatalog.addFile({
+    src: {
+      component: componentVersion.name,
+      version: componentVersion.version,
+      module: 'ROOT',
+      family: 'page',
+      relative: generateSlug(navtitle),
+    },
+  })
+  const { dir: outDir, name: outName } = path.parse(templateFile.out.path)
+  const path_ = outName === templateFile.src.relative ? path.join(outDir, outName + '.adoc') : outDir + '.adoc'
+  contentCatalog.removeFile(templateFile)
   const header = buildAsciiDocHeader(componentVersion, navtitle, doctype)
   const body = aggregateAsciiDoc(
     loadAsciiDoc,
@@ -32,24 +42,27 @@ function produceAggregateDocument (
     mutableAttributes,
     sectionMergeStrategy
   )
-  const relativeSrcPath = `${stem}.adoc`
   return new File({
+    aggregate: true,
     asciidoc: asciidocConfig,
     contents: Buffer.from([...header, ...body].join('\n') + '\n'),
     mediaType: 'text/asciidoc',
-    path: relativeSrcPath,
+    path: path_,
     src: {
       component: componentVersion.name,
       version: componentVersion.version,
-      basename: path.basename(relativeSrcPath),
-      stem,
+      basename: path.basename(path_),
+      stem: path.basename(path_, '.adoc'),
       extname: '.adoc',
     },
   })
 }
 
 function buildAsciiDocHeader (componentVersion, navtitle, doctype = 'book') {
-  const doctitle = navtitle === componentVersion.title ? navtitle : `${componentVersion.title}: ${navtitle}`
+  const navtitlePlain = sanitize(navtitle)
+  const navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
+  let doctitle = navtitleAsciiDoc
+  if (navtitlePlain !== componentVersion.title) doctitle = `${componentVersion.title}: ${doctitle}`
   const version = componentVersion.version === 'master' ? '' : componentVersion.version
   return [
     `= ${doctitle}`,
@@ -88,16 +101,26 @@ function aggregateAsciiDoc (
   asciidocConfig,
   mutableAttributes,
   sectionMergeStrategy,
+  lastComponentVersion = componentVersion,
   level = 0
 ) {
   const buffer = []
   // 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
+  const { content: navtitle, items = [], unresolved, urlType, url } = outlineEntry
+  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['site-url'])
   // 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.aggregated?.includes(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)
@@ -107,16 +130,36 @@ function aggregateAsciiDoc (
         .replace(/^(?:[ \t]*\r\n?|[ \t]*\n)+/, '')
         .trimRight()
     )
+    ;(pagesInOutline.aggregated ??= []).push(page)
     page = new page.constructor(Object.assign({}, page, { contents, mediaType: 'text/asciidoc' }))
-    const { module: module_, relative, origin } = page.src
+    const { component, version, module: module_, relative, origin } = page.src
     const doc = loadAsciiDoc(page, contentCatalog, asciidocConfig)
     const refs = doc.getCatalog().refs
     // NOTE: in Antora, docname is relative src path from module without file extension
     const docname = doc.getAttribute('docname')
     const docnameForId = docname.replace(/[/]/g, '::').replace(/[.]/g, '-')
-    const idprefix = `${module_ === 'ROOT' ? '' : module_ + ':'}${docnameForId}:::`
+    const scopeId = component !== componentVersion.name
+    const idprefix =
+      (scopeId ? component + ':' : '') +
+      (module_ === 'ROOT' ? (scopeId ? ':' : '') : module_ + ':') +
+      docnameForId +
+      ':::'
     buffer.push('')
     buffer.push(`:docname: ${docname}`)
+    if (component !== lastComponentVersion.name) {
+      const thisComponentVersion =
+        component === componentVersion.name && version === componentVersion.version
+          ? componentVersion
+          : contentCatalog.getComponentVersion(component, version)
+      if (thisComponentVersion) {
+        buffer.push(`:page-component-name: ${thisComponentVersion.name}`)
+        buffer.push(`:page-component-version:${thisComponentVersion.version ? ' ' + thisComponentVersion.version : ''}`)
+        buffer.push(':page-version: {page-component-version}')
+        buffer.push(`:page-component-display-version: ${thisComponentVersion.displayVersion}`)
+        buffer.push(`:page-component-title: ${thisComponentVersion.title}`)
+        lastComponentVersion = thisComponentVersion
+      }
+    }
     buffer.push(`:page-module: ${module_}`)
     buffer.push(`:page-relative-src-path: ${relative}`)
     //buffer.push(`:page-origin-type: ${origin.type}`)
@@ -128,7 +171,7 @@ function aggregateAsciiDoc (
     let enclosed
     // NOTE: if level is 0, doctitle has already been added and we're in the document header
     if (level) {
-      if (level === 1 && navtitle === componentVersion.title) {
+      if (level === 1 && navtitlePlain === componentVersion.title) {
         level--
       } else {
         let hlevel = level + 1
@@ -138,12 +181,12 @@ function aggregateAsciiDoc (
         } else {
           buffer.push(`[#${idprefix}]`)
         }
-        buffer.push(`${'='.repeat(hlevel)} ${navtitle}`)
+        buffer.push(`${'='.repeat(hlevel)} ${navtitleAsciiDoc}`)
       }
     } else {
       header.unshift(`[#${idprefix}]`)
     }
-    if (sectionMergeStrategy === 'enclose' && items && doc.hasSections()) {
+    if (sectionMergeStrategy === 'enclose' && hasItems && doc.hasSections()) {
       enclosed = true
       // TODO: make overview section title configurable
       //let overviewTitle = doc.getDocumentTitle()
@@ -170,10 +213,6 @@ function aggregateAsciiDoc (
       buffer.push(`${'='.repeat(hlevel)} ${overviewTitle}`)
       if (toggleSectids) buffer.push(':sectids:')
     }
-    const siteUrl = ((val) => {
-      if (!val || val === '/') return ''
-      return val.charAt(val.length - 1) === '/' ? val.substr(0, val.length - 1) : val
-    })(doc.getAttribute('site-url'))
     const lines = doc.getSourceLines()
     const ignoreLines = []
     // TODO: think more about when multipart is allowed; perhaps configurable
@@ -250,8 +289,8 @@ function aggregateAsciiDoc (
           let pagePart, fragment, targetPage
           const hashIdx = target.indexOf('#')
           if (~hashIdx) {
-            pagePart = target.substr(0, hashIdx)
-            fragment = target.substr(hashIdx + 1)
+            pagePart = 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')) {
@@ -267,20 +306,24 @@ function aggregateAsciiDoc (
               : `<<${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}]`
+            }
             // TODO: handle unresolved page better
-            return siteUrl && (targetPage = contentCatalog.resolvePage(pagePart, page.src)) && targetPage.out
-              ? `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
-              : m
+            return m
           } else if (pagePart.indexOf(':') < 0) {
             if (module_ !== 'ROOT') pagePart = `${module_}:${pagePart}`
           } else if (pagePart.startsWith('ROOT:')) {
-            pagePart = pagePart.substr(5)
+            pagePart = pagePart.slice(5)
           }
           if (!(targetPage = pagesInOutline.get(pagePart))) {
+            if (siteUrl && (targetPage = contentCatalog.resolvePage(pagePart, page.src)) && targetPage.out) {
+              text ||= targetPage.asciidoc?.xreftext || target
+              return `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
+            }
             // TODO: handle unresolved page better
-            return siteUrl && (targetPage = contentCatalog.resolvePage(target, page.src)) && targetPage.out
-              ? `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
-              : m
+            return m
           }
           pagePart = pagePart
             .replace(/[/]/g, '::')
@@ -301,9 +344,8 @@ function aggregateAsciiDoc (
               family: 'attachment',
               relative,
             })
-          return attachment && attachment.out
-            ? `${siteUrl}${attachment.pub.url.replace(/_/g, '{underscore}')}[${text}]`
-            : m
+          // TODO: handle unresolved attachment page
+          return attachment?.out ? `${siteUrl}${attachment.pub.url.replace(/_/g, '{underscore}')}[${text}]` : m
         })
       }
       if (~line.indexOf('image:') && !line.startsWith('image::')) {
@@ -311,7 +353,7 @@ function aggregateAsciiDoc (
           if (isResourceSpec(target)) {
             const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
             // TODO: handle (or report) unresolved image better
-            if (image && image.out) {
+            if (image?.out) {
               image.out.assembled = true
               return `image:${image.out.path.replace(/_/g, '{underscore}')}[${attrlist}]`
             }
@@ -353,14 +395,14 @@ function aggregateAsciiDoc (
           let prefix = ''
           // Q: can we use startsWith('image::') in certain cases?
           let imageMacroOffset = (
-            lastImageMacroAt?.[0] === idx ? line.substr(0, lastImageMacroAt[1]) : line
+            lastImageMacroAt?.[0] === idx ? line.slice(0, lastImageMacroAt[1]) : line
           ).lastIndexOf('image::')
           if (imageMacroOffset > 0) {
             if (
               block.getDocument().isNested() &&
-              (prefix = line.substr(0, imageMacroOffset)).trimRight().endsWith('|')
+              (prefix = line.slice(0, imageMacroOffset)).trimRight().endsWith('|')
             ) {
-              line = line.substr(prefix.length)
+              line = line.slice(prefix.length)
             } else {
               imageMacroOffset = -1
             }
@@ -370,8 +412,8 @@ function aggregateAsciiDoc (
             if (isResourceSpec(target)) {
               const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
               // FIXME: handle (or report) case when image is not resolved
-              if (image && image.out) {
-                const boxedAttrlist = line.substr(line.indexOf('['))
+              if (image?.out) {
+                const boxedAttrlist = line.slice(line.indexOf('['))
                 image.out.assembled = true
                 lines[idx] = `${prefix}image::${image.out.path}${boxedAttrlist}`
               }
@@ -398,7 +440,15 @@ function aggregateAsciiDoc (
             } else if (val !== initialVal) {
               accum.push(`:${name}:${initialVal ? ' ' + initialVal : ''}`)
             }
-          } else if (val != null && !(doc.isAttributeLocked(name) || name === 'doctype' || name === 'leveloffset')) {
+          } else if (
+            !(
+              val == null ||
+              doc.isAttributeLocked(name) ||
+              name === 'doctype' ||
+              name === 'leveloffset' ||
+              name === 'underscore'
+            )
+          ) {
             accum.push(`:!${name}:`)
           }
           return accum
@@ -407,43 +457,51 @@ function aggregateAsciiDoc (
       )
       if (resolvedAttributeEntries.length > 1) buffer.push(...resolvedAttributeEntries)
     }
-  } else {
-    if (level) {
-      if (level === 1 && navtitle === componentVersion.title) {
-        level--
-      } else {
-        buffer.push('')
-        // NOTE: try to toggle sectids; otherwise, fallback to globally unique synthetic ID
-        let toggleSectids, syntheticId
-        if (!('sectids' in asciidocConfig.attributes)) {
+  } else if (level) {
+    if (level === 1 && navtitlePlain === componentVersion.title) {
+      level--
+    } else {
+      buffer.push('')
+      // NOTE: try to toggle sectids; otherwise, fallback to globally unique synthetic ID
+      // Q: should we unset docname, page-module, etc?
+      let toggleSectids, syntheticId
+      if (!('sectids' in asciidocConfig.attributes)) {
+        buffer.push(':!sectids:')
+        toggleSectids = true
+      } else if (typeof asciidocConfig.attributes.sectids === 'string') {
+        if ('sectids' in mutableAttributes) {
           buffer.push(':!sectids:')
           toggleSectids = true
-        } else if (typeof asciidocConfig.attributes.sectids === 'string') {
-          if ('sectids' in mutableAttributes) {
-            buffer.push(':!sectids:')
-            toggleSectids = true
-          } else {
-            syntheticId = `__object-id-${global.Opal.hash(outlineEntry).$object_id()}`
-          }
-        }
-        // Q: should we unset docname, page-module, etc?
-        const sectionTitle = urlType === 'external' ? `${url}[${navtitle.replace(/\]/, '\\]')}]` : navtitle
-        let hlevel = level + 1
-        if (hlevel > 6) {
-          hlevel = 6
-          buffer.push(syntheticId ? `[discrete#${syntheticId}]` : '[discrete]')
-        } else if (syntheticId) {
-          buffer.push(`[#${syntheticId}]`)
+        } else {
+          syntheticId = `__object-id-${global.Opal.hash(outlineEntry).$object_id()}`
         }
-        buffer.push(`${'='.repeat(hlevel)} ${sectionTitle}`)
-        if (toggleSectids) buffer.push(':sectids:')
       }
+      let sectionTitle = navtitleAsciiDoc
+      if (urlType === 'external') {
+        sectionTitle = `${url}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+      } else if (urlType === 'internal' && !unresolved && siteUrl) {
+        const resource = contentCatalog.getFiles().find((it) => it.out && it.pub.url === url)
+        if (resource) sectionTitle = `${siteUrl}${resource.pub.url}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+      }
+      let hlevel = level + 1
+      if (hlevel > 6) {
+        hlevel = 6
+        buffer.push(syntheticId ? `[discrete#${syntheticId}]` : '[discrete]')
+      } else if (syntheticId) {
+        buffer.push(`[#${syntheticId}]`)
+      }
+      buffer.push(`${'='.repeat(hlevel)} ${sectionTitle}`)
+      if (toggleSectids) buffer.push(':sectids:')
     }
   }
 
   const nextLevel = level + 1
-  if (items) {
-    items.forEach((item) => {
+  if (hasItems) {
+    // NOTE: drop first child if same as parent; should we keep if content is different?
+    ;(urlType === 'internal' && urlType === items[0].urlType && url === items[0].url && !items[0].items
+      ? items.slice(1)
+      : items
+    ).forEach((item) => {
       buffer.push(
         ...aggregateAsciiDoc(
           loadAsciiDoc,
@@ -455,6 +513,7 @@ function aggregateAsciiDoc (
           asciidocConfig,
           mutableAttributes,
           sectionMergeStrategy,
+          lastComponentVersion,
           nextLevel
         )
       )
@@ -463,19 +522,12 @@ function aggregateAsciiDoc (
   return buffer
 }
 
-function generateStem (componentVersion, title) {
-  const { name, version } = componentVersion
-  const segments = []
-  if (name !== 'ROOT') segments.push(name)
-  if (version && version !== 'master') segments.push(version)
-  segments.push(
-    title
-      .toLowerCase()
-      .replace(/&.+?;|[^ \p{Alpha}0-9_\-.]/gu, '')
-      .replace(/[ _.]/g, '-')
-      .replace(/--+/g, '-')
-  )
-  return path.join(...segments)
+function generateSlug (title) {
+  return title
+    .toLowerCase()
+    .replace(/&.+?;|[^ \p{Alpha}0-9_\-.]/gu, '')
+    .replace(/[ _.]/g, '-')
+    .replace(/--+/g, '-')
 }
 
 function fixSectionLevels (sections, multipart) {
@@ -512,10 +564,10 @@ function rewriteStyleAttribute (block, lines, idx, idprefix, replacementStyle =
     let rawStyle
     const commaIdx = prevLine.indexOf(',')
     if (~commaIdx) {
-      rawStyle = prevLine.substr(1, commaIdx - 1)
+      rawStyle = prevLine.slice(1, commaIdx - 1)
       if (~rawStyle.indexOf('=')) rawStyle = undefined
     } else if (!~prevLine.indexOf('=')) {
-      rawStyle = prevLine.substr(1, prevLine.length - 2)
+      rawStyle = prevLine.slice(1, prevLine.length - 2)
     }
     if (rawStyle) {
       if (~rawStyle.indexOf('#')) {
@@ -524,10 +576,10 @@ function rewriteStyleAttribute (block, lines, idx, idprefix, replacementStyle =
       } else {
         prevLine = `[${
           replacementStyle ? rawStyle.replace(/^[^.%]*/, replacementStyle) : rawStyle
-        }#${idprefix}${block.getId()}${prevLine.substr(rawStyle.length + 1)}`
+        }#${idprefix}${block.getId()}${prevLine.slice(rawStyle.length + 1)}`
       }
     } else {
-      prevLine = `[${replacementStyle}#${idprefix}${block.getId()}${rawStyle == null ? ',' : ''}${prevLine.substr(1)}`
+      prevLine = `[${replacementStyle}#${idprefix}${block.getId()}${rawStyle == null ? ',' : ''}${prevLine.slice(1)}`
     }
     if (cellSpec) prevLine = `${cellSpec}|${prevLine}`
     lines[idx - 1] = prevLine

package/lib/produce-aggregate-documents.js

@@ -5,6 +5,8 @@ const filterComponentVersions = require('./filter-component-versions')
 const produceAggregateDocument = require('./produce-aggregate-document')
 const selectMutableAttributes = require('./select-mutable-attributes')
 
+const IMAGE_MACRO_RX = /^image::?(.+?)\[(.*?)\]$/
+
 function produceAggregateDocuments (loadAsciiDoc, contentCatalog, assemblerConfig) {
   const { insertStartPage, rootLevel, sectionMergeStrategy, asciidoc: assemblerAsciiDocConfig } = assemblerConfig
   const assemblerAsciiDocAttributes = Object.assign({}, assemblerAsciiDocConfig.attributes)
@@ -20,26 +22,32 @@ function produceAggregateDocuments (loadAsciiDoc, contentCatalog, assemblerConfi
       const mergedAsciiDocConfig = Object.assign({}, componentVersionAsciiDocConfig, {
         attributes: Object.assign({ revdate }, componentVersionAsciiDocConfig.attributes, assemblerAsciiDocAttributes),
       })
+      const mergedAsciiDocAttributes = mergedAsciiDocConfig.attributes
+      Object.entries(mergedAsciiDocAttributes).forEach(([name, val]) => {
+        const match = name.endsWith('-image') && val.startsWith('image:') && IMAGE_MACRO_RX.exec(val)
+        if (!(match && isResourceRef(match[1]))) return
+        // Q should we allow image to be resolved relative to component version?
+        const image = contentCatalog.resolveResource(match[1], undefined, 'image', ['image'])
+        if (!image?.out) return
+        mergedAsciiDocAttributes[name] = `image:${image.out.path}[${match[2]}]`
+        image.out.assembled = true
+      })
       const rootEntry = { content: title }
-      const startPage = contentCatalog.getComponentVersionStartPage(componentName, version)
-      let startPageUrl
-      if (startPage && insertStartPage) {
-        if (includedInNav(navigation, (startPageUrl = startPage.pub.url))) {
-          startPageUrl = undefined
-        } else {
-          Object.assign(rootEntry, { url: startPageUrl, urlType: 'internal' })
+      let startPage = contentCatalog.getComponentVersionStartPage(componentName, version)
+      if (startPage && startPage.src.component === componentName && startPage.src.version === version) {
+        if (insertStartPage && !includedInNav(navigation, startPage.pub.url)) {
+          Object.assign(rootEntry, { url: startPage.pub.url, urlType: 'internal' })
         }
-      }
-      // Q: should we always use a reference page here?
-      const startPage_ =
-        startPage ??
-        createFile({
+      } else {
+        // Q: should we always use a reference page as startPage for computing mutableAttributes?
+        startPage = createFile({
           component: componentVersion.name,
           version: componentVersion.version,
           relative: '.reference-page.adoc',
           origin: (componentVersion.origins || [])[0],
         })
-      const mutableAttributes = selectMutableAttributes(loadAsciiDoc, contentCatalog, startPage_, mergedAsciiDocConfig)
+      }
+      const mutableAttributes = selectMutableAttributes(loadAsciiDoc, contentCatalog, startPage, mergedAsciiDocConfig)
       delete mutableAttributes.doctype
       accum = accum.concat(
         prepareOutlines(navigation, rootEntry, rootLevel).map((outline) =>
@@ -56,10 +64,10 @@ function produceAggregateDocuments (loadAsciiDoc, contentCatalog, assemblerConfi
           )
         )
       )
-      mergedAsciiDocConfig.attributes.doctype = doctype
+      mergedAsciiDocAttributes.doctype = doctype
       sourceHighlighter
-        ? (mergedAsciiDocConfig.attributes['source-highlighter'] = sourceHighlighter)
-        : delete mergedAsciiDocConfig.attributes['source-highlighter']
+        ? (mergedAsciiDocAttributes['source-highlighter'] = sourceHighlighter)
+        : delete mergedAsciiDocAttributes['source-highlighter']
       return accum
     },
     []
@@ -113,15 +121,22 @@ function includedInNav (items, url) {
   return items.find((it) => it.url === url || includedInNav(it.items || [], url))
 }
 
+function isResourceRef (target) {
+  return ~target.indexOf(':') && !(~target.indexOf('://') || (target.startsWith('data:') && ~target.indexOf(',')))
+}
+
 // when root level is 0, merge the navigation into the rootEntry
 // when root level is 1, create navigation per navigation menu
 // in this case, if there's only a single navigation menu with no title, promote each top-level item to a menu
 function prepareOutlines (navigation, rootEntry, rootLevel) {
   if (rootLevel === 0 || navigation.length === 1) {
-    const navBranch =
-      navigation.length === 1
-        ? navigation[0]
-        : { items: navigation.reduce((navTree, it) => navTree.concat(it.content ? it : it.items), []) }
+    let navBranch
+    if (navigation.length === 1) {
+      navBranch = navigation[0]
+    } else {
+      const items = navigation.reduce((accum, it) => accum.concat(it.content ? it : it.items), [])
+      navBranch = items.length ? { items } : {}
+    }
     return rootLevel === 0 || navBranch.content ? [Object.assign(rootEntry, navBranch)] : navBranch.items
   }
   return navigation.reduce((navTree, it) => navTree.concat(it.content ? it : it.items), [rootEntry])

package/lib/util/sanitize.js

@@ -0,0 +1,13 @@
+'use strict'
+
+const XML_TAG_RX = /<[^>]+>/g
+const XML_SPECIAL_CHARS = { '&lt;': '<', '&gt;': '>', '&amp;': '&' }
+const XML_SPECIAL_CHARS_RX = /&(?:[lg]t|amp);/g
+
+function sanitize (str) {
+  if (~str.indexOf('<')) str = str.replace(XML_TAG_RX, '')
+  if (~str.indexOf('&')) str = str.replace(XML_SPECIAL_CHARS_RX, (m) => XML_SPECIAL_CHARS[m])
+  return str
+}
+
+module.exports = sanitize

package/lib/util/unconvert-inline-asciidoc.js

@@ -0,0 +1,95 @@
+'use strict'
+
+const ATTRIBUTE_REFERENCE_RX = /\{[a-z0-9_][a-z0-9_-]*\}/g
+const STRICT_WORD_CHAR_RX = /[\p{L}\d_]/u
+const WORD_CHAR_RX = /[\p{L}\d_;}:<>]/u
+
+const MARK_FOR_TAG = { code: '`', em: '_', mark: '#', span: '#', strong: '*' }
+const SKIP_SPAN = { icon: '<i ', image: '<img ' }
+
+module.exports = (str) => {
+  if (!str) return str
+  let matchIndex = str.indexOf('<')
+  if (!~matchIndex) return ~str.indexOf('{') ? str.replace(ATTRIBUTE_REFERENCE_RX, '\\$&') : str
+  let current = { contents: '' }
+  const stack = [current]
+  let lastIndex = 0
+  do {
+    if (matchIndex > lastIndex) {
+      const matched = str.slice(lastIndex, matchIndex)
+      current.contents += ~matched.indexOf('{') ? matched.replace(ATTRIBUTE_REFERENCE_RX, '\\$&') : matched
+    }
+    const isCloseTag = str[++matchIndex] === '/' ? ++matchIndex : false
+    let tagName = str.slice(matchIndex, (lastIndex = str.indexOf('>', matchIndex) + 1) - 1)
+    if (isCloseTag) {
+      const parent = current // TODO expect tagName to equal current.tagName
+      stack.pop()
+      current = stack[stack.length - 1]
+      if (parent.mark) {
+        let { contents, mark, id, role } = parent
+        const attrlist = (id ? '#' + id : '') + (role ? '.' + role.replace(/ /g, '.') : '')
+        if (
+          current.mark === mark ||
+          current.mark === '_' ||
+          isWordChar(str.charAt(lastIndex), true) ||
+          isWordChar(current.contents[current.contents.length - 1] || current.mark)
+        ) {
+          mark = mark.repeat(2)
+        }
+        current.contents += (attrlist ? '[' + attrlist + ']' : '') + mark + contents + mark
+      } else {
+        current.contents += parent.contents
+      }
+    } else {
+      let attrs, attrlistIndex, role
+      if (~(attrlistIndex = tagName.indexOf(' '))) {
+        role = (attrs = parseAttrlist(tagName.slice(attrlistIndex))).class
+        tagName = tagName.slice(0, attrlistIndex)
+      }
+      if (tagName === 'img') {
+        current.contents += 'image:' + attrs.src + '[' + attrs.alt + ']'
+      } else if (tagName === 'i' && current.tagName === 'span' && current.role === 'icon') {
+        current.contents += 'icon:' + role.slice(6) + '[]'
+        lastIndex += 4
+      } else {
+        let check, mark
+        const id = attrs?.id
+        if (tagName !== 'span' || id || (role && !((check = SKIP_SPAN[role]) && str.startsWith(check, lastIndex)))) {
+          mark = MARK_FOR_TAG[tagName]
+        }
+        stack.push((current = { tagName, role, id, mark, contents: '' }))
+      }
+    }
+  } while (~(matchIndex = str.indexOf('<', lastIndex)))
+  const rest = str.slice(lastIndex)
+  if (rest) current.contents += ~rest.indexOf('{') ? rest.replace(ATTRIBUTE_REFERENCE_RX, '\\$&') : rest
+  return current.contents
+}
+
+function parseAttrlist (str) {
+  let lastIndex = 0
+  const attrs = {}
+  while (str.charAt(lastIndex++) === ' ') {
+    const spaceIndex = str.indexOf(' ', lastIndex)
+    const equalsIndex = str.indexOf('=', lastIndex)
+    if (~spaceIndex && spaceIndex < equalsIndex) {
+      attrs[str.slice(lastIndex, (lastIndex = spaceIndex))] = true
+    } else if (~equalsIndex) {
+      const name = str.slice(lastIndex, equalsIndex)
+      const valueIndex = equalsIndex + 1
+      attrs[name] =
+        str.charAt(valueIndex) === '"'
+          ? str.slice(valueIndex + 1, (lastIndex = str.indexOf('"', valueIndex + 1) + 1) - 1)
+          : str.slice(valueIndex, (lastIndex = ~spaceIndex ? spaceIndex : str.length))
+    } else {
+      attrs[str.slice(lastIndex)] = true
+      break
+    }
+  }
+  return attrs
+}
+
+function isWordChar (str, strict) {
+  if (!str) return false
+  return (strict ? STRICT_WORD_CHAR_RX : WORD_CHAR_RX).test(str)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/assembler",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.9",
   "description": "An extension library for Antora that assembles content from multiple pages into a single AsciiDoc file to converted and publish.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
@@ -15,8 +15,8 @@
   },
   "scripts": {
     "test": "_mocha test",
-    "prepublishOnly": "node $npm_config_local_prefix/npm/prepublishOnly.js",
-    "postpublish": "node $npm_config_local_prefix/npm/postpublish.js"
+    "prepublishOnly": "npx -y downdoc --prepublish",
+    "postpublish": "npx -y downdoc --postpublish"
   },
   "main": "lib/index.js",
   "exports": {
@@ -28,6 +28,9 @@
     "./produce-aggregate-documents": "./lib/produce-aggregate-documents.js",
     "./select-mutable-attributes": "./lib/select-mutable-attributes.js"
   },
+  "imports": {
+    "#unconvert-inline-asciidoc": "./lib/util/unconvert-inline-asciidoc.js"
+  },
   "dependencies": {
     "@antora/expand-path-helper": "~2.0",
     "braces": "~3.0",
@@ -36,8 +39,8 @@
     "js-yaml": "~4.1"
   },
   "devDependencies": {
-    "@antora/asciidoc-loader": "3.0.1",
-    "@antora/site-publisher": "3.0.1"
+    "@antora/asciidoc-loader": "~3.1",
+    "@antora/site-publisher": "~3.1"
   },
   "engines": {
     "node": ">=16.0.0"