@antora/assembler 1.0.0-rc.4 → 1.0.0-rc.6

package/lib/assemble-content.js

@@ -11,11 +11,12 @@ const produceAssemblyFiles = require('./produce-assembly-files')
 const PromiseQueue = require('./util/promise-queue')
 const runCommand = require('@antora/run-command-helper')
 
-const invariably = { true: () => true, false: () => false, new: () => ({}), void: () => undefined }
+const invariably = { new: () => ({}), null: () => null, void: () => undefined }
 const PACKAGE_NAME = require('../package.json').name
 const NEWLINE_RX = /(?:\r?\n)+/
 
-async function assembleContent (playbook, contentCatalog, converter, { configSource, navigationCatalog }) {
+async function assembleContent (playbook, contentCatalog, converter, providers) {
+  const { configSource, navigationCatalog, componentVersionFilter } = providers
   const {
     convert = converter,
     getDefaultCommand,
@@ -23,7 +24,8 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
     backend: targetBackend = targetExtname.substring(1),
     embedReferenceStyle = 'relative',
     mediaType: targetMediaType,
-    loggerName = PACKAGE_NAME,
+    loggerName = `${PACKAGE_NAME} [${targetBackend}-exporter]`,
+    xmlCompliant,
   } = converter ?? {}
   const assemblerConfig = await loadConfig.call(this, configSource, playbook, '-' + targetBackend)
   if (assemblerConfig.enabled === false || !contentCatalog.publishableFamilies?.has('export')) return []
@@ -38,8 +40,9 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
   const { loadAsciiDoc = require('@antora/asciidoc-loader') } = generatorFunctions
   const { assembly: assemblyConfig, build: buildConfig } = assemblerConfig
   assemblyConfig.embedReferenceStyle = embedReferenceStyle
+  if (xmlCompliant) assemblyConfig.xmlIds ??= true
   const profile = (assemblyConfig.profile ??= targetBackend)
-  const intrinsicAttributes = { 'loader-assembler': '' }
+  const intrinsicAttributes = { 'loader-assembler': '', 'assembler-root-level': assemblyConfig.rootLevel }
   const cwd = (buildConfig.cwd ??= process.cwd())
   if (profile) {
     buildConfig.dir ??= ospath.join(playbook.dir ?? process.cwd(), `build/assembler/${profile}`)
@@ -62,7 +65,8 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
     loadAsciiDoc,
     contentCatalog,
     assemblerConfig,
-    generateSelectAssemblyProfile(context, contentCatalog, assemblyConfig, intrinsicAttributes, navigationCatalog)
+    generateSelectAssemblyProfile(context, contentCatalog, assemblyConfig, intrinsicAttributes, navigationCatalog),
+    typeof componentVersionFilter === 'function' ? componentVersionFilter : undefined
   )
   if (!(assemblyFiles.length && typeof convert === 'function')) return assemblyFiles
   buildConfig.command ??= typeof getDefaultCommand === 'function' ? await getDefaultCommand(cwd, playbook) : null
@@ -75,8 +79,7 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
     .add(
       assemblyFiles.map((doc) => async () => {
         const relativeToOutput = embedReferenceStyle === 'output-relative'
-        const convertAttributes = prepareConvertAttributes(doc, targetExtname, relativeToOutput, assemblerConfig)
-        if (buildConfig.mkdirs) await fsp.mkdir(convertAttributes.outdir, { recursive: true, force: true })
+        const convertAttributes = await prepareConvertAttributes(doc, targetExtname, relativeToOutput, assemblerConfig)
         return boundConvert(doc, convertAttributes, buildConfig, helpers).then((result) =>
           boundResolveFileOrContents(result, convertAttributes, buildConfig, loggerName).then((fileOrContents) =>
             coerceToExportFormat(doc, targetBackend, targetExtname, targetMediaType, fileOrContents)
@@ -150,29 +153,34 @@ function generateSelectAssemblyProfile (context, contentCatalog, baseModel, intr
     const attributes = Object.assign({}, baseModel.attributes)
     const model = Object.assign({}, baseModel, overrides, { attributes, logger })
     if (!overrides) return Object.assign(model, { navigation: navigation || componentVersion.navigation })
+    if ('rootLevel' in overrides) attributes['assembler-root-level'] = overrides.rootLevel
     delete model.navFiles
     delete model.messages
-    if (overrides.attributes) Object.entries(overrides.attributes).forEach(([name, val]) => (attributes[name] = val))
+    if (overrides.attributes) {
+      for (const [name, val] of Object.entries(overrides.attributes)) {
+        if (!(name in intrinsicAttributes)) attributes[name] = val
+      }
+    }
     if (navigation) return Object.assign(model, { navigation })
     overrides.messages?.forEach(boundSendToLog)
     const navFiles = overrides.navFiles
     if (!navFiles) return Object.assign(model, { navigation: componentVersion.navigation })
     if (!navFiles.length) return Object.assign(model, { navigation: [] })
     model.navigation = buildAlternateNavigation(contentCatalog, componentVersion, navFiles, {
-      attributes: intrinsicAttributes,
+      attributes: model.attributes,
     })
     return model
   }
 }
 
-function prepareConvertAttributes (doc, targetExtname, relativeToOutput, assemblerConfig) {
+async function prepareConvertAttributes (doc, targetExtname, relativeToOutput, assemblerConfig) {
   const {
     asciidoc: { attributes: docAttributes } = { attributes: {} },
     extname: docfilesuffix,
     path: reldocfile,
     src: { family, relative },
   } = doc
-  const { cwd = process.cwd(), dir = cwd } = assemblerConfig.build
+  const { cwd = process.cwd(), dir = cwd, mkdirs } = assemblerConfig.build
   const docname = family + '$' + relative.substring(0, relative.length - docfilesuffix.length)
   const docfile = ospath.join(dir, reldocfile)
   const outdir = ospath.dirname(docfile)
@@ -182,31 +190,54 @@ function prepareConvertAttributes (doc, targetExtname, relativeToOutput, assembl
     docdir,
     docfile,
     docfilesuffix,
-    'docname@': docname,
+    docname: `${docname}@`,
     imagesdir: '',
     outdir,
     outfile,
     outfilesuffix: targetExtname,
-    toArgs (optionFlag) {
+    toArgs (attributeOptionFlag, outputOptionFlag) {
       const args = []
-      for (let [name, val] of Object.entries(this)) {
-        if (val) {
-          val = name + '=' + val
-        } else if (val === '') {
-          if (name === 'asciidoctor-log-integration') {
-            args.push('-r', require.resolve('#asciidoctor-log-adapter'))
-            continue
-          }
-          val = name
+      let requireAsciidoctorLogAdapter
+      for (const [name, val] of Object.entries(this)) {
+        let optionValue
+        if (name === 'asciidoctor-log-integration') {
+          if ((val ?? false) !== false) requireAsciidoctorLogAdapter = val
+          continue
+        } else if ((val ?? false) === false) {
+          optionValue = `${name}!${val === false ? '=@' : ''}`
         } else {
-          val = `${name}!${val === false ? '@' : ''}`
+          optionValue = val === '' ? name : name + '=' + val
         }
-        args.push(optionFlag, val)
+        args.push(attributeOptionFlag, optionValue)
       }
+      if (requireAsciidoctorLogAdapter) args.push('-r', requireAsciidoctorLogAdapter)
+      if (outputOptionFlag) args.push(outputOptionFlag, this.outfile)
       return args
     },
   })
-  return Object.defineProperty(attributes, 'toArgs', { enumerable: false })
+  Object.defineProperty(attributes, 'outfilesuffix', {
+    get () {
+      return ospath.extname(this.outfile)
+    },
+    set (value) {
+      const outfile = this.outfile
+      const extname = ospath.extname(outfile)
+      if (extname && outfile.endsWith(extname)) this.outfile = outfile.substring(0, outfile.length - extname.length)
+      this.outfile += value
+    },
+  })
+  Object.defineProperty(attributes, 'toArgs', { enumerable: false })
+  if (mkdirs) await fsp.mkdir(outdir, { recursive: true, force: true })
+  if (attributes['asciidoctor-log-integration'] != null) {
+    const scriptSourcePath = require.resolve('#asciidoctor-log-adapter')
+    let scriptTargetPath = scriptSourcePath
+    if (attributes['asciidoctor-log-integration'] === 'copy-to-build-dir') {
+      scriptTargetPath = ospath.join(dir, 'asciidoctor-log-adapter.rb')
+      await fsp.cp(scriptSourcePath, scriptTargetPath, { force: true, recursive: true })
+    }
+    attributes['asciidoctor-log-integration'] = scriptTargetPath
+  }
+  return attributes
 }
 
 function coerceToExportFormat (assemblyFile, targetBackend, targetExtname, targetMediaType, fileOrContents) {
@@ -219,7 +250,8 @@ function coerceToExportFormat (assemblyFile, targetBackend, targetExtname, targe
   const { path: sourcePath, extname: sourceExtname } = file
   const relativeWithoutExtname = file.src.relative.substring(0, file.src.relative.length - sourceExtname.length)
   const newPath = sourcePath.substring(0, sourcePath.length - sourceExtname.length) + targetExtname
-  Object.assign(file, { mediaType: (file.src.mediaType = targetMediaType), path: newPath })
+  Object.assign(file, { mediaType: (file.src.mediaType = targetMediaType), path: (file.src.path = newPath) })
+  delete file.src.abspath
   file.src.basename = path.basename((file.src.relative = relativeWithoutExtname + (file.src.extname = targetExtname)))
   return file
 }
@@ -242,8 +274,9 @@ function prepareWorkspace (publishFiles, assemblyFiles, buildConfig) {
   }
   if (keepSource) {
     for (const file of assemblyFiles) {
-      file.src.contents = file.contents
       file.out = { path: file.path }
+      file.src.contents = file.contents
+      file.src.abspath = ospath.join(dir, file.path)
       files.push(file)
     }
   }
@@ -254,7 +287,7 @@ function prepareWorkspace (publishFiles, assemblyFiles, buildConfig) {
   })
 }
 
-async function resolveFileOrContents (convertResult, convertAttributes, buildConfig, loggerName) {
+function resolveFileOrContents (convertResult, convertAttributes, buildConfig, loggerName) {
   let fileOrContents
   if (convertResult?.status != null) {
     if ('file' in convertResult) {
@@ -265,12 +298,14 @@ async function resolveFileOrContents (convertResult, convertAttributes, buildCon
       fileOrContents = convertResult.stdout
     }
     let logger, match
-    if (buildConfig.stderrSink === 'log' && convertResult.stderr.length && (logger = this.getLogger(loggerName))) {
+    if (buildConfig.stderrSink === 'log' && convertResult.stderr?.length && (logger = this.getLogger(loggerName))) {
       const docfile = convertAttributes.docfile
       const command = buildConfig.command
+      const file = { path: docfile }
       const stderr = convertResult.stderr.toString().trimEnd()
+      const additionalLines = ['Additional stderr lines from command:']
       stderr.split(NEWLINE_RX).forEach((line) => {
-        const ctx = { command, file: { path: docfile } }
+        const ctx = { command, file }
         if (line.charAt() === '{' && line.charAt(line.length - 1) === '}') {
           const entry = JSON.parse(line)
           if (entry.name) ctx.program = entry.name
@@ -286,17 +321,17 @@ async function resolveFileOrContents (convertResult, convertAttributes, buildCon
           if (lineno) ctx.line = parseInt(lineno, 10)
           logger[level === 'WARNING' ? 'warn' : level.toLowerCase()](ctx, msg)
         } else {
-          logger.info(ctx, line)
+          additionalLines.push(line)
         }
       })
+      if (additionalLines.length > 1) logger.info({ command, file }, additionalLines.join('\n'))
     }
   } else if (convertResult !== undefined) {
-    return convertResult
+    return Promise.resolve(convertResult)
   }
-  if (fileOrContents !== undefined) return fileOrContents
+  if (fileOrContents !== undefined) return Promise.resolve(fileOrContents)
   const outfile = convertAttributes.outfile
-  const outfileExists = await fsp.access(outfile).then(invariably.true, invariably.false)
-  return outfileExists ? new LazyReadable(() => fs.createReadStream(outfile)) : null
+  return fsp.access(outfile).then(() => new LazyReadable(() => fs.createReadStream(outfile)), invariably.null)
 }
 
 function isBound (obj) {

package/lib/configure.js

@@ -7,24 +7,26 @@ function configure (context, ...args) {
 }
 
 function internalConfigure (converter, config = {}, providers = {}) {
-  this.once('componentsRegistered', ({ contentCatalog, assemblerProfiles }) => {
-    contentCatalog.publishableFamilies.add('export')
-    if (assemblerProfiles) return
-    this.updateVariables({ assemblerProfiles: getAssemblerProfiles(contentCatalog) })
-  })
+  if (!this.listeners('beforeProcess').includes(enableKeepSource)) {
+    this.once('componentsRegistered', ({ contentCatalog, assemblerProfiles }) => {
+      contentCatalog.publishableFamilies.add('export')
+      if (!assemblerProfiles) this.updateVariables({ assemblerProfiles: getAssemblerProfiles(contentCatalog) })
+    })
 
-  this.once('beforeProcess', enableKeepSource)
+    this.once('beforeProcess', enableKeepSource)
+  }
 
   this.once('navigationBuilt', async ({ playbook, contentCatalog }) => {
-    const { assembleContent = require('./assemble-content'), ...assembleContentConfig } = providers
-    if (assembleContentConfig.configSource?.constructor === Object) {
-      await assembleContent.call(this, playbook, contentCatalog, converter, assembleContentConfig)
+    const { assembleContent = require('./assemble-content'), ...assembleContentProviders } = providers
+    if (config.configSource?.constructor === Object) {
+      assembleContentProviders.configSource = config.configSource
+      await assembleContent.call(this, playbook, contentCatalog, converter, assembleContentProviders)
     } else {
       const singleConfig = !('configFiles' in config)
       const configFiles = singleConfig ? config.configFile : config.configFiles
       for (const configSource of Array.isArray(configFiles) ? configFiles : [configFiles]) {
-        const assembleContentConfigWithConfigSource = Object.assign({}, assembleContentConfig, { configSource })
-        await assembleContent.call(this, playbook, contentCatalog, converter, assembleContentConfigWithConfigSource)
+        const assembleContentProvidersWithConfigSource = Object.assign({}, assembleContentProviders, { configSource })
+        await assembleContent.call(this, playbook, contentCatalog, converter, assembleContentProvidersWithConfigSource)
         if (singleConfig) break
       }
     }

package/lib/filter-component-versions.js

@@ -5,7 +5,7 @@ const { filterCollection, compilePattern } = require('./util/matcher')
 const VERSION_SEPARATOR_RX = /@(?!\()(?=(\w)?)/g
 const US = '\x1f'
 
-function filterComponentVersions (components, { names: patterns, prereleases = true }) {
+function filterComponentVersions ({ names: patterns, prereleases = true }, components) {
   if (!patterns.length) return []
   const candidateMap = components.reduce((accum, { name: componentName, latest, versions }) => {
     for (const version of versions) {

package/lib/load-config.js

@@ -9,6 +9,7 @@ const yaml = require('js-yaml')
 const { LEGACY_ASSEMBLY_KEYS } = require('./constants')
 const CAMEL_CASE_STOP_PATHS = ['asciidoc.attributes', 'assembly.attributes']
 const PACKAGE_NAME = require('../package.json').name
+const YAML_SCHEMA = yaml.CORE_SCHEMA.withTags(yaml.mergeTag)
 
 function loadConfig (configSource, playbook, preferredQualifier = '') {
   let resolvedConfigSource
@@ -36,11 +37,11 @@ function loadConfig (configSource, playbook, preferredQualifier = '') {
               }
               return {}
             }
-            return fsp
-              .readFile(resolvedConfigSource)
-              .then((data) =>
-                Object.assign(camelCaseKeys(yaml.load(data), CAMEL_CASE_STOP_PATHS), { file: resolvedConfigSource })
-              )
+            return fsp.readFile(resolvedConfigSource).then((data) =>
+              Object.assign(camelCaseKeys(yaml.load(data, { schema: YAML_SCHEMA }), CAMEL_CASE_STOP_PATHS), {
+                file: resolvedConfigSource,
+              })
+            )
           })
   ).then((config) => {
     if (config.enabled === false) return config
@@ -133,7 +134,7 @@ function loadConfig (configSource, playbook, preferredQualifier = '') {
   })
 }
 
-function camelCaseKeys (o, stopPaths = [], p = undefined) {
+function camelCaseKeys (o, stopPaths, p = undefined) {
   if (Array.isArray(o)) return o.map((it) => camelCaseKeys(it, stopPaths, p))
   if (o == null || o.constructor !== Object) return o
   const pathPrefix = p ? p + '.' : ''

package/lib/produce-assembly-file.js

@@ -20,6 +20,7 @@ const DISCARD_ATTRIBUTE_NAMES = [
   'doctype',
   'leveloffset',
   'preface-title',
+  'assembly-doctype',
   'assembly-header-attributes',
   'assembly-navtitle',
   'assembly-slug',
@@ -39,8 +40,8 @@ function produceAssemblyFile (
   assemblyModel
 ) {
   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)
+  if (outline.urlType === 'internal' && !pagesByUrl.has(outline.pathname) && !outline.items?.length) return
   const { rootLevel, xmlIds } = assemblyModel
   const idSeparators = {
     prefix:
@@ -77,6 +78,7 @@ function produceAssemblyFile (
     mutableAttributes,
     assemblyModel
   )
+  if (buffer[buffer.doctypeIdx] === ':doctype: article') buffer.splice(buffer.doctypeIdx, 1)
   const stem =
     (buffer.slug ? sanitizeSlug(buffer.slug) : generateSlug(rootLevel === 0 ? 'index' : buffer.navtitle)) ||
     'export-' + (assemblyModel.stemSeq = (assemblyModel.exportSeq ?? 0) + 1)
@@ -88,7 +90,7 @@ function produceAssemblyFile (
     src: { component, version, componentVersion, module: 'ROOT', family: 'export', relative: stem + '.adoc' },
     pub: false,
   })
-  file.path = file.out.path // use out path as file path so assets can easily be published to same hierarchy
+  file.path = file.src.path = file.out.path // use out path as path so assets can be published to same hierarchy
   delete file.out
   return file
 }
@@ -124,7 +126,6 @@ function prepareAsciiDocConfig (contentCatalog, ctx, pagesInOutline, asciidocCon
 }
 
 function buildAsciiDocHeader (componentVersion, navtitle, assemblyModel) {
-  const doctype = assemblyModel.doctype ?? 'book'
   const navtitlePlain = sanitize(navtitle)
   const navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
   const doctitle = (componentVersion.title === navtitlePlain ? '' : componentVersion.title + ': ') + navtitleAsciiDoc
@@ -133,7 +134,7 @@ function buildAsciiDocHeader (componentVersion, navtitle, assemblyModel) {
   const buffer = [
     `= ${doctitle}`,
     ...(version ? [`:revnumber: ${displayVersion}`] : []),
-    ...(doctype === 'article' ? [] : [`:doctype: ${doctype}`]),
+    `:doctype: ${assemblyModel.doctype ?? 'book'}`,
     ':underscore: _',
     // Q: should we pass these via the CLI so they cannot be modified?
     `:page-component-name: ${componentVersion.name}`,
@@ -142,17 +143,22 @@ function buildAsciiDocHeader (componentVersion, navtitle, assemblyModel) {
     `:page-component-display-version: ${displayVersion}`,
     `:page-component-title: ${componentVersion.title}`,
   ]
+  buffer.doctypeIdx = version ? 2 : 1
   return Object.assign(buffer, { navtitle })
 }
 
 function selectPagesInOutline (outlineEntry, pagesByUrl, 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) {
-    accum.set(createResourceKey(page.src), page)
-    accum.set(outlineEntry.url, page)
+  const { urlType, url, hash, unresolved, items = [] } = outlineEntry
+  if (urlType === 'internal' && !unresolved) {
+    const pathname = (outlineEntry.pathname ??= hash ? url.substring(0, url.length - hash.length) : url)
+    let page
+    if (!accum.has(pathname) && (page = pagesByUrl.get(pathname))) {
+      accum.set(createResourceKey(page.src), page)
+      accum.set(pathname, page)
+    }
   }
-  for (const item of outlineEntry.items || []) selectPagesInOutline(item, pagesByUrl, accum)
+  for (const item of items) selectPagesInOutline(item, pagesByUrl, accum)
   return accum
 }
 
@@ -172,21 +178,22 @@ function mergeAsciiDoc (
   level = 0,
   supportsParts = false
 ) {
-  const { items = [], roles = [], unresolved, urlType, url, hash } = outlineEntry
+  const { items = [], roles = [], unresolved, urlType, url, pathname, hash } = outlineEntry
   // TODO: we could try to be smart about it and make sure the page with fragment is included at least once
-  if (hash || roles.includes('site-only')) {
+  if (roles.includes('site-only')) {
     buffer.inBody ??= false
     return buffer
   }
-  let navtitle = outlineEntry.navtitle ?? outlineEntry.content
+  const assembled = pagesInOutline.assembled
+  // 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(pathname) : undefined
+  let navtitle = outlineEntry.navtitle ?? (page && hash ? page.asciidoc.navtitle : outlineEntry.content)
   let navtitlePlain = sanitize(navtitle)
   let navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
   const { filetype, linkReferenceStyle, pubRoot, sectionMergeStrategy, siteRoot, logger, rootLevel } = assemblyModel
-  const assembled = pagesInOutline.assembled
-  // 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 doctype = assemblyModel.doctype ?? 'book'
   const atDocumentRoot = !buffer.inBody
-  const atBookRoot = atDocumentRoot && !level && assemblyModel.doctype === 'book' && (supportsParts = true)
+  let atBookRoot = atDocumentRoot && !level && doctype === 'book' && (supportsParts = true)
   const hasItems = items.length > 0
   if (page && !assembled.pages.has(page)) {
     const contents = page.src.contents
@@ -198,6 +205,7 @@ function mergeAsciiDoc (
       Object.assign({}, page, { contents: trimAsciiDoc(contents), mediaType: page.src.mediaType })
     )
     const doc = loadAsciiDoc(pageAsAsciiDoc, contentCatalog, asciidocConfig)
+    doc.catalog.syntheticIds = {}
     doc.logger = logger
       ? Object.assign(doc.getLogger().$dup(), {
           delegate: {
@@ -210,6 +218,11 @@ function mergeAsciiDoc (
     doc.source_header_attributes ??= doc.parent.$to_h()
     const isRootPage = atDocumentRoot && !level
     const { component, version, module: module_, relative, origin } = page.src
+    const doctypeOverride = doc.getAttribute('assembly-doctype')
+    if (doctypeOverride) {
+      if (doctypeOverride !== doctype) buffer[buffer.doctypeIdx] = `:doctype: ${doctypeOverride}`
+      if (doctypeOverride !== 'book') atBookRoot = supportsParts = false
+    }
     if (isRootPage && doc.hasAttribute('assembly-slug')) buffer.slug = doc.getAttribute('assembly-slug')
     let hasAssemblyNavtitleAttr
     if ((hasAssemblyNavtitleAttr = !!doc.getAttribute('assembly-navtitle'))) {
@@ -278,6 +291,7 @@ function mergeAsciiDoc (
       for (const entry of processDocumentHeader(doc, lines, ignoreLines, isRootPage)) {
         if (entry.type === 'author_line') {
           buffer.splice(1, 0, entry.lines[0])
+          buffer.doctypeIdx += 1
           buffer.endHeaderIdx += 1
         } else if (entry.type === 'attribute_entry') {
           const name = entry.name
@@ -370,6 +384,7 @@ function mergeAsciiDoc (
           // Q: should we use htitleAsciiDoc to generate ID if not {empty} instead of pageStyle
           pageFragment = `#_${idSeparators.coordinate}${pageIdLeader}${pageStyle}`
           buffer.unshift(`[#${pageId}]`)
+          buffer.doctypeIdx += 1
         } else {
           pageFragment = `#${pageId}`
         }
@@ -400,6 +415,7 @@ function mergeAsciiDoc (
       buffer.push(`${'='.repeat(heading.level)} ${heading.title}`)
     } else if (atDocumentRoot) {
       buffer.unshift(`[#${pageId}]`)
+      buffer.doctypeIdx += 1
     }
     if (sectionMergeStrategy === 'enclose' && hasItems && hasSections && !(atDocumentRoot && heading)) {
       // TODO: make overview section title configurable
@@ -475,7 +491,7 @@ function mergeAsciiDoc (
       if (~ignoreLines.indexOf(idx)) continue
       let line = lines[idx]
       if (line.startsWith('//')) {
-        if (line[2] !== '/') continue
+        if (line.charAt(2) !== '/') continue
         if (line.length > 3 && line === '/'.repeat(line.length)) {
           if (skipping) {
             if (line === skipping) skipping = undefined
@@ -609,7 +625,7 @@ function mergeAsciiDoc (
       )
       if (resolvedAttributeEntries.length > 1) safePush(buffer, resolvedAttributeEntries)
     }
-  } else if (level) {
+  } else if (level && !hash) {
     if (atDocumentRoot && rootLevel === 0 && navtitlePlain === componentVersion.title) {
       buffer.inBody ??= false
       level--
@@ -621,7 +637,7 @@ function mergeAsciiDoc (
       if (urlType === 'external') {
         sectionTitle = `${url}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
       } else if (urlType === 'internal' && !unresolved) {
-        const resource = files.find((it) => it.pub.url === url)
+        const resource = files.find((it) => it.pub.url === pathname)
         if (resource) {
           if (resource.src.family === 'page' && pagesInOutline.has(resource.pub.url)) {
             const refid = generateScopedId(resource.src, componentVersion, idSeparators, filetype, true)
@@ -640,7 +656,7 @@ function mergeAsciiDoc (
   if (hasItems) {
     const nextLevel = level + 1
     // 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
+    ;(urlType === 'internal' && items[0].urlType === 'internal' && pathname === items[0].url && !items[0].items?.length
       ? items.slice(1)
       : items
     ).forEach((item) => {
@@ -807,10 +823,18 @@ function safePush (onto, entries) {
 
 function generateIdFromTitle (titleAsciiDoc, idSeparators, idLeader) {
   const Section = this.$class().$const_get('::Asciidoctor::Section')
-  const baseId = Section.$generate_id(titleAsciiDoc, this)
-  if (idLeader) return `_${idSeparators.coordinate}${idLeader}${baseId}`
-  this.getCatalog().refs['$[]='](baseId, true)
-  return `_${idSeparators.coordinate}${baseId}`
+  const baseId = Section.$generate_id(titleAsciiDoc, this) // refs in catalog will always be empty
+  let id = `_${idSeparators.coordinate}${idLeader ?? ''}${baseId}`
+  const syntheticIds = (this.catalog.syntheticIds ??= {})
+  if (id in syntheticIds) {
+    const sep = (this.getAttribute('idseparator') ?? '_').charAt()
+    let cnt = this.$class().$const_get('::Asciidoctor::Compliance').unique_id_start_index
+    let candidate
+    while ((candidate = `${id}${sep}${cnt}`) in syntheticIds) cnt++
+    id = candidate
+  }
+  syntheticIds[id] = true
+  return id
 }
 
 module.exports = produceAssemblyFile

package/lib/produce-assembly-files.js

@@ -6,7 +6,13 @@ const selectMutableAttributes = require('./select-mutable-attributes')
 
 const ATTR_REF_RX = /\\?\{(\w[\w-]*)\}/g
 
-function produceAssemblyFiles (loadAsciiDoc, contentCatalog, assemblerConfig, selectAssemblyProfile) {
+function produceAssemblyFiles (
+  loadAsciiDoc,
+  contentCatalog,
+  assemblerConfig,
+  selectAssemblyProfile,
+  selectComponentVersions
+) {
   const { assembly: assemblyConfig } = assemblerConfig
   selectAssemblyProfile ??= (componentVersion) => ({
     attributes: assemblyConfig.attributes,
@@ -26,106 +32,104 @@ function produceAssemblyFiles (loadAsciiDoc, contentCatalog, assemblerConfig, se
   const publishableFiles = contentCatalog.getFiles().filter((file) => file.out && file.pub)
   let siteRoot
   const configMdc = assemblerConfig.file ? { file: { path: assemblerConfig.file } } : {}
-  return filterComponentVersions(contentCatalog.getComponents(), assemblerConfig.componentVersionFilter).reduce(
-    (accum, componentVersion) => {
-      const assemblyModel = selectAssemblyProfile(componentVersion)
-      const { attributes: assemblyAttributes, logger, navigation, rootLevel } = assemblyModel
-      if (!navigation) return accum
-      const contextualLogger = logger ? { warn: logger.warn.bind(logger, configMdc) } : undefined
-      const { name: componentName, version, title } = componentVersion
-      const componentVersionAsciiDocConfig = getAsciiDocConfigWithAsciidoctorReducerExtension(componentVersion)
-      let sourceHighlighter
-      if ('source-highlighter' in assemblyAttributes) {
-        sourceHighlighter = assemblyAttributes['source-highlighter']
-        delete assemblyAttributes['source-highlighter']
+  selectComponentVersions ??= filterComponentVersions.bind(null, assemblerConfig.componentVersionFilter)
+  return selectComponentVersions(contentCatalog.getComponents()).reduce((accum, componentVersion) => {
+    const assemblyModel = selectAssemblyProfile(componentVersion)
+    const { attributes: assemblyAttributes, logger, navigation, rootLevel } = assemblyModel
+    if (!navigation) return accum
+    const contextualLogger = logger ? { warn: logger.warn.bind(logger, configMdc) } : undefined
+    const { name: componentName, version, title } = componentVersion
+    const componentVersionAsciiDocConfig = getAsciiDocConfigWithAsciidoctorReducerExtension(componentVersion)
+    let sourceHighlighter
+    if ('source-highlighter' in assemblyAttributes) {
+      sourceHighlighter = assemblyAttributes['source-highlighter']
+      delete assemblyAttributes['source-highlighter']
+    }
+    const mergedAsciiDocAttributes = collateAsciiDocAttributes(
+      Object.assign({}, componentVersionAsciiDocConfig.attributes),
+      assemblyAttributes,
+      contextualLogger
+    )
+    const mergedAsciiDocConfig = Object.assign({}, componentVersionAsciiDocConfig, {
+      attributes: mergedAsciiDocAttributes,
+    })
+    assemblyModel.filetype = baseAssemblyAttributes['assembler-filetype']
+    const outDirname = (assemblyModel.outDirname = contentCatalog.createFile({
+      src: {
+        component: componentName,
+        version,
+        componentVersion,
+        module: 'ROOT',
+        family: 'export',
+        relative: 'index.adoc',
+      },
+    }).out.dirname)
+    assemblyModel.pubRoot = outDirname ? '/' + outDirname : ''
+    assemblyModel.siteRoot =
+      siteRoot === undefined
+        ? (siteRoot ??= ((val) => {
+            if (!val) return null
+            if (val.charAt(val.length - 1) === '/') val = val.substring(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 if (!(assemblyModel.filetype === 'pdf' && assemblyModel.linkReferenceStyle === 'relative')) {
+      assemblyModel.linkReferenceStyle = 'absolute'
+    }
+    const rootEntry = { content: title }
+    let startPage =
+      'startPage' in componentVersion
+        ? componentVersion.startPage
+        : contentCatalog.resolvePage('index.adoc', { component: componentName, version })
+    if (startPage && startPage.src.component === componentName && startPage.src.version === version) {
+      if (assemblyModel.insertStartPage) {
+        const navtitle = startPage.asciidoc?.navtitle || rootEntry.content
+        Object.assign(rootEntry, { navtitle, url: startPage.pub.url, urlType: 'internal', roles: ['page'] })
       }
-      const mergedAsciiDocAttributes = collateAsciiDocAttributes(
-        Object.assign({}, componentVersionAsciiDocConfig.attributes),
-        assemblyAttributes,
-        contextualLogger
-      )
-      const mergedAsciiDocConfig = Object.assign({}, componentVersionAsciiDocConfig, {
-        attributes: mergedAsciiDocAttributes,
-      })
-      assemblyModel.filetype = baseAssemblyAttributes['assembler-filetype']
-      const outDirname = (assemblyModel.outDirname = contentCatalog.createFile({
+    } else {
+      // Q: should we always use a reference page as startPage for computing mutableAttributes?
+      startPage = contentCatalog.createFile({
         src: {
-          component: componentName,
-          version,
+          component: componentVersion.name,
+          version: componentVersion.version,
           componentVersion,
           module: 'ROOT',
-          family: 'export',
+          family: 'page',
           relative: 'index.adoc',
+          origin: (componentVersion.origins || [])[0],
         },
-      }).out.dirname)
-      assemblyModel.pubRoot = outDirname ? '/' + outDirname : ''
-      assemblyModel.siteRoot =
-        siteRoot === undefined
-          ? (siteRoot ??= ((val) => {
-              if (!val) return null
-              if (val.charAt(val.length - 1) === '/') val = val.substring(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 if (!(assemblyModel.filetype === 'pdf' && assemblyModel.linkReferenceStyle === 'relative')) {
-        assemblyModel.linkReferenceStyle = 'absolute'
-      }
-      const rootEntry = { content: title }
-      let startPage =
-        'startPage' in componentVersion
-          ? componentVersion.startPage
-          : contentCatalog.resolvePage('index.adoc', { component: componentName, version })
-      if (startPage && startPage.src.component === componentName && startPage.src.version === version) {
-        if (assemblyModel.insertStartPage) {
-          const navtitle = startPage.asciidoc?.navtitle || rootEntry.content
-          Object.assign(rootEntry, { navtitle, url: startPage.pub.url, urlType: 'internal', roles: ['page'] })
-        }
-      } else {
-        // Q: should we always use a reference page as startPage for computing mutableAttributes?
-        startPage = contentCatalog.createFile({
-          src: {
-            component: componentVersion.name,
-            version: componentVersion.version,
-            componentVersion,
-            module: 'ROOT',
-            family: 'page',
-            relative: 'index.adoc',
-            origin: (componentVersion.origins || [])[0],
-          },
-        })
-        startPage.path = ['modules', startPage.src.module, startPage.src.family + 's', startPage.src.relative].join('/')
+      })
+      startPage.path = ['modules', startPage.src.module, startPage.src.family + 's', startPage.src.relative].join('/')
+    }
+    const mutableAttributes = selectMutableAttributes(loadAsciiDoc, contentCatalog, startPage, mergedAsciiDocConfig)
+    prepareOutlines(navigation, rootEntry, rootLevel).reduce((any, outline) => {
+      const assemblyFile = produceAssemblyFile(
+        loadAsciiDoc,
+        contentCatalog,
+        componentVersion,
+        outline,
+        publishableFiles,
+        mergedAsciiDocConfig,
+        mutableAttributes,
+        assemblyModel
+      )
+      if (!assemblyFile) return any
+      // NOTE restore source highlighter for conversion if defined in Assembler config
+      if (sourceHighlighter !== undefined) {
+        assemblyFile.asciidoc.attributes['source-highlighter'] = sourceHighlighter
+      } else if (assemblyModel.filetype !== 'html') {
+        delete assemblyFile.asciidoc.attributes['source-highlighter']
       }
-      const mutableAttributes = selectMutableAttributes(loadAsciiDoc, contentCatalog, startPage, mergedAsciiDocConfig)
-      prepareOutlines(navigation, rootEntry, rootLevel).reduce((any, outline) => {
-        const assemblyFile = produceAssemblyFile(
-          loadAsciiDoc,
-          contentCatalog,
-          componentVersion,
-          outline,
-          publishableFiles,
-          mergedAsciiDocConfig,
-          mutableAttributes,
-          assemblyModel
-        )
-        if (!assemblyFile) return any
-        // NOTE restore source highlighter for conversion if defined in Assembler config
-        if (sourceHighlighter !== undefined) {
-          assemblyFile.asciidoc.attributes['source-highlighter'] = sourceHighlighter
-        } else if (assemblyModel.filetype !== 'html') {
-          delete assemblyFile.asciidoc.attributes['source-highlighter']
-        }
-        return !!accum.push(assemblyFile)
-      }, false)
-      return accum
-    },
-    []
-  )
+      return !!accum.push(assemblyFile)
+    }, false)
+    return accum
+  }, [])
 }
 
 function getAsciiDocConfigWithAsciidoctorReducerExtension (componentVersion) {

package/lib/util/rewriter.js

@@ -19,7 +19,7 @@ function rewriteXrefs (
   doc,
   sourceLocation
 ) {
-  return line.replace(/(?<![\\+])xref:((?:\.\/)?[\p{Alpha}0-9_/.{#].*?)\[(|[\s\S]*?[^\\])\]/gu, (_, target, text) =>
+  return line.replace(/(?<![\\+])xref:((?:\.\/|:)?[\p{Alpha}0-9_/.{#].*?)\[(|[\s\S]*?[^\\])\]/gu, (_, target, text) =>
     rewriteXref(
       target,
       text,
@@ -87,7 +87,7 @@ function rewriteXref (
     const linkAttrlist = text
       ? (~text.indexOf(',') ? `"${text}"` : text) + ',role=unresolved'
       : (~target.indexOf(':') ? `${rawTarget},` : '') + 'role=unresolved'
-    return `link:${rawTarget}[${linkAttrlist}]`
+    return `link:${rawTarget.charAt() === ':' ? resourceId.module + rawTarget : rawTarget}[${linkAttrlist}]`
   }
   if (fragment === resource.asciidoc.id) fragment = ''
   if (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/assembler",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.6",
   "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)",
@@ -38,10 +38,10 @@
     "#unconvert-inline-asciidoc": "./lib/util/unconvert-inline-asciidoc.js"
   },
   "dependencies": {
-    "@asciidoctor/reducer": "~1.1",
     "@antora/expand-path-helper": "~3.0",
     "@antora/run-command-helper": "~1.1",
-    "js-yaml": "~4.3"
+    "@asciidoctor/reducer": "~1.1",
+    "js-yaml": "~5.2"
   },
   "devDependencies": {
     "@antora/asciidoc-loader": "3.2.0-rc.2",