@antora/assembler 1.0.0-beta.2 → 1.0.0-beta.20

package/adapters/asciidoctor/jsonl-logger.rb

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

package/lib/assemble-content.js

@@ -5,18 +5,30 @@ const fs = require('node:fs')
 const { promises: fsp } = fs
 const LazyReadable = require('./util/lazy-readable')
 const loadConfig = require('./load-config')
+const logCommand = require('./log-command')
 const ospath = require('node:path')
 const { posix: path } = ospath
 const produceAssemblyFiles = require('./produce-assembly-files')
 const PromiseQueue = require('./util/promise-queue')
+const runCommand = require('@antora/run-command-helper')
 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)
-  if (!assemblerConfig) return [] // TODO consider removing and doing this another way
+  const {
+    convert = converter,
+    getDefaultCommand,
+    extname: targetExtname = '',
+    backend: targetBackend = targetExtname.slice(1),
+    embedReferenceStyle = 'relative',
+    mediaType: targetMediaType,
+    loggerName = PACKAGE_NAME,
+  } = converter ?? {}
+  const assemblerConfig = await loadConfig.call(this, playbook, configSource, '-' + targetBackend)
+  if (assemblerConfig.enabled === false) return []
   const context = isBound(this)
     ? this
     : {
@@ -26,12 +38,13 @@ 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 { assembly: assemblyConfig, build: buildConfig } = assemblerConfig
-  const { profile = targetBackend } = assemblyConfig
+  assemblyConfig.embedReferenceStyle = embedReferenceStyle
+  const profile = (assemblyConfig.profile ??= targetBackend)
   const intrinsicAttributes = { 'loader-assembler': '' }
+  buildConfig.cwd ??= process.cwd()
   if (profile) {
-    buildConfig.dir ??= ospath.join(playbook.dir ?? process.cwd(), `build/assembler-${profile}`)
+    buildConfig.dir ??= ospath.join(playbook.dir ?? process.cwd(), `build/assembler/${profile}`)
     intrinsicAttributes[`assembler-profile-${profile}`] = ''
     intrinsicAttributes['assembler-profile'] = profile
     if (targetBackend) {
@@ -39,30 +52,38 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
       intrinsicAttributes['assembler-backend'] = targetBackend
     }
   } else {
-    buildConfig.dir ??= ospath.join(playbook.dir ?? process.cwd(), 'build/assembler')
+    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)
+  Object.assign(assemblyConfig.attributes, intrinsicAttributes)
   const assemblyFiles = produceAssemblyFiles(
     loadAsciiDoc,
     contentCatalog,
     assemblerConfig,
-    createResolveAssemblyModel(context, contentCatalog, assemblyConfig, intrinsicAttributes, navigationCatalog)
+    generateSelectAssemblyProfile(context, contentCatalog, assemblyConfig, intrinsicAttributes, navigationCatalog)
   )
-  const { convert = converter, extname: targetExtname, mediaType: targetMediaType } = converter ?? {}
-  if (!(convert && assemblyFiles.length)) return assemblyFiles
+  if (!(assemblyFiles.length && typeof convert === 'function')) return assemblyFiles
+  if (buildConfig.command == null && typeof getDefaultCommand === 'function') {
+    buildConfig.command = await getDefaultCommand(buildConfig.cwd)
+  }
   const { publishSite: publishFiles = require('@antora/site-publisher') } = generatorFunctions
-  await prepareWorkspace(publishFiles, assemblyFiles, contentCatalog, buildConfig)
+  await prepareWorkspace(publishFiles, assemblyFiles, buildConfig)
+  const helpers = { logCommand: logCommand.bind(context, loggerName), runCommand }
   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, assemblerConfig)
         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, helpers).then((result) => {
+          const fileOrContents = resolveFileOrContents.call(context, result, convertAttributes, buildConfig, loggerName)
+          return coerceToExportFormat(doc, targetBackend, targetExtname, targetMediaType, fileOrContents)
+        })
       })
     )
     .toPromise()
@@ -85,7 +106,13 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
         }
         pages.forEach((fragment, page) => {
           const assemblerMeta = (page.assembler ??= {})
-          ;(assemblerMeta.exports ??= []).push({ fragment, file })
+          const exports = (assemblerMeta.exports ??= [])
+          const exportEntry = { fragment, file }
+          const insertIdx = exports.findIndex(
+            ({ file: candidate }) =>
+              !(candidate.src.component === page.src.component && candidate.src.version === page.src.version)
+          )
+          ~insertIdx ? exports.splice(insertIdx, 0, exportEntry) : exports.push(exportEntry)
           const extnameProp = extname.slice(1)
           if (extnameProp in assemblerMeta) return
           Object.defineProperty(assemblerMeta, extnameProp, {
@@ -99,71 +126,97 @@ async function assembleContent (playbook, contentCatalog, converter, { configSou
     })
 }
 
-function createResolveAssemblyModel (context, contentCatalog, shared, intrinsicAttributes, navigationCatalog) {
+/**
+ * Generates a function that selects the active assembly profile, initializes an assembly model using
+ * the keys from the profile as well as any inherited shared keys, builds the navigation for the assembly, and
+ * returns the initialized assembly model. The assembly model is further populated after the call to this function.
+ */
+function generateSelectAssemblyProfile (context, contentCatalog, baseModel, 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({}, baseModel, { attributes: Object.assign({}, baseModel.attributes), navigation, logger })
     }
   }
-  const boundSendToLog = sendToLog.bind(context.getLogger ? context.getLogger(PACKAGE_NAME) : undefined)
-  const { buildNavigation = require('@antora/navigation-builder') } = context.getFunctions()
+  const boundSendToLog = sendToLog.bind(logger)
+  const {
+    buildNavigation = require('@antora/navigation-builder'),
+    buildAlternateNavigation = buildNavigation.buildAlternateNavigation ??
+      buildAlternateNavigationShim.bind(null, buildNavigation),
+  } = context.getFunctions()
   return (componentVersion) => {
+    const attributes = Object.assign({}, baseModel.attributes)
     const componentVersionProfiles = assemblerProfiles.get(componentVersion.version + '@' + componentVersion.name)
-    const overrides =
-      componentVersionProfiles?.get(intrinsicAttributes['assembler-profile']) ?? componentVersionProfiles?.get()
+    const overrides = componentVersionProfiles?.get(baseModel.profile) ?? componentVersionProfiles?.get() ?? {}
     const { navFiles, messages } = overrides
-    const model = Object.assign({}, shared, overrides)
+    Object.entries(overrides.attributes ?? {}).forEach(([name, val]) => (attributes[name] = val))
+    const model = Object.assign({}, baseModel, overrides, { attributes, logger })
     delete model.navFiles
     delete model.messages
     const navigationOverride = navigationCatalog?.getNavigation(componentVersion.name, componentVersion.version)
     if (navigationOverride) return Object.assign(model, { navigation: navigationOverride })
     messages?.forEach(boundSendToLog)
-    model.navigation = componentVersion.navigation
-    if (!navFiles) return model
+    if (!navFiles) return Object.assign(model, { navigation: componentVersion.navigation })
     if (!navFiles.length) return Object.assign(model, { navigation: [] })
-    const navigation_ = model.navigation
-    const asciidoc_ = componentVersion.asciidoc
-    componentVersion.asciidoc = Object.assign({}, asciidoc_, {
-      attributes: Object.assign({}, asciidoc_.attributes, intrinsicAttributes),
+    model.navigation = buildAlternateNavigation(contentCatalog, componentVersion, navFiles, {
+      attributes: intrinsicAttributes,
     })
-    buildNavigation(
-      new Proxy(contentCatalog, {
-        get (target, property) {
-          const method = target[property]
-          if (property !== 'findBy') return method
-          return (criteria) => (toJSON(criteria) === '{"family":"nav"}' ? navFiles : method.call(target, criteria))
-        },
-      })
-    )
-    model.navigation = componentVersion.navigation
-    Object.assign(componentVersion, { asciidoc: asciidoc_, navigation: navigation_ })
     return model
   }
 }
 
-function prepareConvertAttributes (doc, targetExtname, buildConfig) {
+function buildAlternateNavigationShim (
+  buildNavigation,
+  contentCatalog,
+  componentVersion,
+  navFiles,
+  asciidocConfigOverrides
+) {
+  const { asciidoc: asciidoc_, navigation: navigation_ } = componentVersion
+  const asciidocConfig = (componentVersion.asciidoc = Object.assign({}, asciidoc_))
+  if (asciidocConfigOverrides) {
+    const attributesOverrides =
+      'attributes' in asciidocConfigOverrides
+        ? { attributes: Object.assign({}, asciidocConfig.attributes, asciidocConfigOverrides.attributes) }
+        : undefined
+    Object.assign(asciidocConfig, asciidocConfigOverrides, attributesOverrides)
+  }
+  const contentCatalogProxy = new Proxy(contentCatalog, {
+    get (target, property) {
+      const method = target[property]
+      if (property !== 'findBy') return method
+      return (criteria) => (toJSON(criteria) === '{"family":"nav"}' ? navFiles : method.call(target, criteria))
+    },
+  })
+  buildNavigation(contentCatalogProxy)
+  const navigation = componentVersion.navigation
+  Object.assign(componentVersion, { asciidoc: asciidoc_, navigation: navigation_ })
+  return navigation
+}
+
+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 } = buildConfig
+  const { cwd = process.cwd(), dir = cwd } = assemblerConfig.build
   const docname = family + '$' + relative.slice(0, relative.length - docfilesuffix.length)
   const docfile = ospath.join(dir, reldocfile)
-  const docdir = dir
-  const imagesdir = ''
+  const outdir = ospath.dirname(docfile)
+  const docdir = relativeToOutput ? dir : outdir
   const outfile = docfile.slice(0, docfile.length - docfilesuffix.length) + targetExtname
-  const attributes = Object.assign({}, docAttributes, {
+  const attributes = Object.assign({ revdate: `${assemblerConfig.assembly.revdate}@` }, docAttributes, {
     docdir,
     docfile,
     docfilesuffix,
     'docname@': docname,
-    imagesdir,
-    outdir: ospath.dirname(docfile),
+    imagesdir: '',
+    outdir,
     outfile,
     outfilesuffix: targetExtname,
     toArgs (optionFlag, command) {
@@ -173,11 +226,15 @@ function prepareConvertAttributes (doc, targetExtname, buildConfig) {
         if (val) {
           val = `${name}=${padCharRef && typeof val.charAt === 'function' && val.charAt() === '&' ? ' ' : ''}${val}`
         } else if (val === '') {
+          if (name === 'asciidoctor-log-integration') {
+            args.push('-r', require.resolve('#asciidoctor-log-adapter'))
+            continue
+          }
           val = name
         } else {
           val = `!${name}${val === false ? '@' : ''}`
         }
-        args.push('-a', val)
+        args.push(optionFlag, val)
       }
       return args
     },
@@ -206,7 +263,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()
@@ -217,13 +274,57 @@ function prepareWorkspace (publishFiles, assemblyFiles, contentCatalog, buildCon
       outPaths.add(asset.out.path)
     }
   }
-  if (keepSource) files.push(...assemblyFiles.map((file) => Object.assign(file, { out: { path: file.path } })))
+  if (keepSource) {
+    for (const file of assemblyFiles) {
+      file.src.contents = file.contents
+      file.out = { path: file.path }
+      files.push(file)
+    }
+  }
   return publishFiles({ output: { clean, dir } }, { getFiles: () => files })
 }
 
+function resolveFileOrContents (convertResult, convertAttributes, buildConfig, loggerName) {
+  let fileOrContents
+  if (convertResult?.status != null) {
+    fileOrContents = 'file' in convertResult ? convertResult.file : convertResult.contents
+    let logger, match
+    if (buildConfig.stderrSink === 'log' && convertResult.stderr.length && (logger = this.getLogger(loggerName))) {
+      const docfile = convertAttributes.docfile
+      const command = buildConfig.command
+      const stderr = convertResult.stderr.toString().trimEnd()
+      stderr.split(NEWLINE_RX).forEach((line) => {
+        const ctx = { command, file: { path: docfile } }
+        if (line.charAt() === '{' && line.charAt(line.length - 1) === '}') {
+          const entry = JSON.parse(line)
+          if (entry.name) ctx.program = entry.name
+          if (entry.file?.line) ctx.line = entry.file.line
+          logger[entry.level](ctx, entry.msg)
+        } else if ((match = /^([^:]+):(\d+): warning: (.+)/.exec(line))) {
+          const [, scriptPath, lineno, msg] = match
+          ctx.stack = [{ file: { path: scriptPath }, line: parseInt(lineno, 10) }]
+          logger.warn(ctx, msg)
+        } else if ((match = /^asciidoctor: ([A-Z]+): (?:[^:]+: line (\d+): )?(.+)/.exec(line))) {
+          // NOTE we don't care about the filename in the message since it can only be docfile
+          const [, level, lineno, msg] = match
+          if (lineno) ctx.line = parseInt(lineno, 10)
+          logger[level === 'WARNING' ? 'warn' : level.toLowerCase()](ctx, msg)
+        } else {
+          logger.info(ctx, line)
+        }
+      })
+    }
+  } else if (convertResult !== undefined) {
+    return convertResult
+  }
+  return fileOrContents === undefined
+    ? new LazyReadable(() => fs.createReadStream(convertAttributes.outfile))
+    : fileOrContents
+}
+
 function isBound (obj) {
   if (obj == null) return false
-  for (const p in obj) return true
+  for (const _ in obj) return true
   return false
 }
 

package/lib/configure.js

@@ -6,24 +6,46 @@ function configure (context, ...args) {
 
 function internalConfigure (converter, config = {}, providers = {}) {
   this.once('componentsRegistered', ({ contentCatalog, assemblerProfiles }) => {
-    this.updateVariables(assemblerProfiles ? undefined : { assemblerProfiles: getAssemblerProfiles(contentCatalog) })
+    if (assemblerProfiles) return
+    this.updateVariables({ assemblerProfiles: getAssemblerProfiles(contentCatalog) })
   })
 
-  this.once('beforeProcess', ({ siteAsciiDocConfig }) => {
-    siteAsciiDocConfig.keepSource = true
-  })
+  this.once('beforeProcess', enableKeepSource)
 
   this.once('navigationBuilt', async ({ playbook, contentCatalog }) => {
     const { assembleContent = require('./assemble-content'), ...assembleContentConfig } = providers
-    assembleContentConfig.configSource ??= config.configFile
-    await assembleContent.call(this, playbook, contentCatalog, converter, assembleContentConfig)
+    if (assembleContentConfig.configSource?.constructor === Object) {
+      await assembleContent.call(this, playbook, contentCatalog, converter, assembleContentConfig)
+    } 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)
+        if (singleConfig) break
+      }
+    }
   })
 }
 
+function enableKeepSource ({ siteAsciiDocConfig }) {
+  if (siteAsciiDocConfig.keepSource instanceof Boolean) return
+  siteAsciiDocConfig.keepSource = Object.assign(new Boolean(true), { oldValue: siteAsciiDocConfig.keepSource })
+  this.once('navigationBuilt', restoreKeepSource)
+}
+
+function restoreKeepSource ({ siteAsciiDocConfig, contentCatalog }) {
+  if (!(siteAsciiDocConfig.keepSource instanceof Boolean)) return
+  if ((siteAsciiDocConfig.keepSource = siteAsciiDocConfig.keepSource.oldValue)) return
+  contentCatalog.getPages((page) => delete page.src.contents)
+}
+
 function getAssemblerProfiles (contentCatalog, assemblerProfiles = new Map()) {
   contentCatalog.getComponents().forEach((component) => {
     component.versions.forEach((componentVersion) => {
-      const source = componentVersion.nav?.origin
+      const source =
+        componentVersion.nav?.origin ??
+        [...(componentVersion.origins ?? [])].find((it) => it.descriptor?.ext?.assembler)
       const assemblerConfig = getAssemblerConfigFromDescriptor(source?.descriptor)
       if (!assemblerConfig) return
       const componentVersionRef = `${componentVersion.version}@${componentVersion.name}`
@@ -64,14 +86,10 @@ function getAssemblerProfiles (contentCatalog, assemblerProfiles = new Map()) {
 }
 
 function getAssemblerConfigFromDescriptor (descriptor = {}) {
-  let assemblerConfig = descriptor.ext?.assembler
+  const assemblerConfig = descriptor.ext?.assembler
   if (!assemblerConfig) return
-  if (Array.isArray(assemblerConfig)) {
-    if (!assemblerConfig.length) return
-  } else {
-    assemblerConfig = [assemblerConfig]
-  }
-  return assemblerConfig
+  if (!Array.isArray(assemblerConfig)) return [assemblerConfig]
+  if (assemblerConfig.length) return assemblerConfig
 }
 
 function initNavFile (file, component, version, index) {

package/lib/filter-component-versions.js

@@ -36,12 +36,13 @@ function compilePatterns (patterns) {
   })
 }
 
-function filterComponentVersions (components, patterns) {
+function filterComponentVersions (components, { names: patterns, prereleases = true }) {
   if (!patterns.length) return []
   const rxs = compilePatterns(patterns)
   return components.reduce((accum, { latest, versions }) => {
     accum.push(
       ...versions.filter((version) => {
+        if (!prereleases && version.prerelease && version !== latest) return false
         let matched
         for (const rx of rxs) {
           let voteIfMatched

package/lib/load-config.js

@@ -5,29 +5,49 @@ const fsp = require('node:fs/promises')
 const os = require('node:os')
 const yaml = require('js-yaml')
 
-function loadConfig (playbook, configSource = './antora-assembler.yml') {
+const ASSEMBLY_KEYS = [
+  'rootLevel',
+  'insertStartPage',
+  'sectionMergeStrategy',
+  'linkReferenceStyle',
+  'dropExplicitXrefText',
+]
+const CAMEL_CASE_STOP_PATHS = ['asciidoc.attributes', 'assembly.attributes']
+const PACKAGE_NAME = require('../package.json').name
+
+function loadConfig (playbook, configSource, preferredQualifier = '') {
+  let resolvedConfigSource
   return (
-    configSource.constructor === Object
+    configSource?.constructor === Object
       ? Promise.resolve(configSource)
-      : fsp
-          .access((configSource = expandPath(configSource, { dot: playbook.dir })))
-          .then(
-            () => true,
-            () => false
-          )
-          .then((exists) =>
-            exists ? fsp.readFile(configSource).then((data) => camelCaseKeys(yaml.load(data), ['asciidoc'])) : {}
-          )
+      : fileExists(
+          (resolvedConfigSource = expandPath(configSource ?? `./antora-assembler${preferredQualifier}.yml`, {
+            dot: playbook.dir,
+          }))
+        )
+          .then((exists) => {
+            if (exists || configSource || !preferredQualifier) return exists
+            return fileExists(
+              (resolvedConfigSource = resolvedConfigSource.slice(0, -(preferredQualifier.length + 4)) + '.yml')
+            )
+          })
+          .then((exists) => {
+            if (!exists) {
+              let logger
+              if (configSource && (logger = this?.getLogger?.(PACKAGE_NAME))) {
+                const ctx = { file: { path: configSource } }
+                logger.warn(ctx, 'Could not resolve config file; reverting to default settings')
+              }
+              return {}
+            }
+            return fsp
+              .readFile(resolvedConfigSource)
+              .then((data) =>
+                Object.assign(camelCaseKeys(yaml.load(data), CAMEL_CASE_STOP_PATHS), { file: resolvedConfigSource })
+              )
+          })
   ).then((config) => {
-    if (config.enabled === false) return undefined
-    let asciidocAttrs
-    if (!config.asciidoc) {
-      config.asciidoc = { attributes: (asciidocAttrs = {}) }
-    } else if (!(asciidocAttrs = config.asciidoc.attributes)) {
-      config.asciidoc.attributes = asciidocAttrs = {}
-    }
-    if (!('revdate' in asciidocAttrs)) asciidocAttrs.revdate = getLocalDate()
-    asciidocAttrs['page-partial'] = null
+    if (config.enabled === false) return config
     const remapComponentVersionsKey = !('componentVersionFilter' in config)
     const componentVersionFilter = (config.componentVersionFilter ??= {})
     if (remapComponentVersionsKey && 'componentVersions' in config) {
@@ -42,25 +62,49 @@ 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]
       }
     }
-    if (!('doctype' in assembly)) assembly.doctype = 'doctype' in asciidocAttrs ? asciidocAttrs.doctype : 'book'
-    delete asciidocAttrs.doctype
+    let assemblyAttrs
+    if ('attributes' in assembly) {
+      assemblyAttrs = assembly.attributes ?? {}
+      if ('asciidoc' in config) delete config.asciidoc
+    } else if ('asciidoc' in config) {
+      assemblyAttrs = assembly.attributes = config.asciidoc?.attributes ?? {}
+      delete config.asciidoc
+    } else {
+      assemblyAttrs = assembly.attributes = {}
+    }
+    assemblyAttrs['page-partial'] = null
+    config.asciidoc = Object.defineProperty({}, 'attributes', {
+      get: function () {
+        return this.assembly.attributes
+      }.bind(config),
+    })
+    if (!('doctype' in assembly)) assembly.doctype = 'doctype' in assemblyAttrs ? assemblyAttrs.doctype : 'book'
+    delete assemblyAttrs.doctype
     if (!('rootLevel' in assembly)) assembly.rootLevel = 0
     if (!('insertStartPage' in assembly)) assembly.insertStartPage = true
     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'
+    }
+    assembly.revdate = getLocalDate()
     const build = (config.build ??= {})
     if (build.dir === '$' + '{playbook.output.dir}') {
       throw new Error('Not implemented')
     }
     build.dir &&= expandPath(build.dir, { dot: playbook.dir })
-    build.cwd = playbook.dir // use playbook.dir for finding and loading require scripts
+    // used as cwd of command (and any scripts it requires)
+    build.cwd = build.cwd == null ? playbook.dir : expandPath(build.cwd, { dot: playbook.dir })
     if (!('clean' in build) && 'output' in playbook) build.clean = playbook.output.clean
     if (!('publish' in build)) build.publish = true
     if ('keepAggregateSource' in build) {
@@ -70,6 +114,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
   })
 }
@@ -86,6 +138,13 @@ function camelCaseKeys (o, stopPaths = [], p = undefined) {
   return accum
 }
 
+function fileExists (path) {
+  return fsp.access(path).then(
+    () => true,
+    () => false
+  )
+}
+
 function getLocalDate (now = new Date()) {
   return new Date(now - now.getTimezoneOffset() * 60000).toISOString().split('T')[0]
 }

package/lib/log-command.js

@@ -0,0 +1,18 @@
+'use strict'
+
+function logCommand (loggerName, command, file, convertAttributes, attributeOptionFlagOrArgs) {
+  const logger = this?.getLogger(loggerName)
+  if (!logger?.isLevelEnabled('debug')) return
+  const { docfile, 'assembler-filetype': filetype } = convertAttributes
+  const args = Array.isArray(attributeOptionFlagOrArgs)
+    ? attributeOptionFlagOrArgs
+    : attributeOptionFlagOrArgs
+      ? convertAttributes.toArgs(attributeOptionFlagOrArgs, command)
+      : []
+  const ctx = { command: [command].concat(args).join(' '), file: { path: docfile } }
+  const msg = `Running external command to export assembly in %s to %s: %s`
+  const componentVersionStr = file.src.version ? `${file.src.version}@${file.src.component}` : file.src.component
+  logger.debug(ctx, msg, componentVersionStr, filetype, file.src.relative)
+}
+
+module.exports = logCommand