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

package/lib/produce-assembly-file.js

@@ -1,15 +1,32 @@
 'use strict'
 
 const createAsciiDocFile = require('./util/create-asciidoc-file')
-const path = require('node:path/posix')
+const createResourceKey = require('./util/create-resource-key')
+const generateScopedId = require('./util/generate-scoped-id')
+const { resolveLinkTarget } = require('./util/resolver')
+const {
+  rewriteXrefs,
+  rewriteImageAttr,
+  rewriteImageRef,
+  rewriteInlineImages,
+  rewriteStyleAttribute,
+} = require('./util/rewriter')
 const sanitize = require('./util/sanitize')
 const unconvertInlineAsciiDoc = require('./util/unconvert-inline-asciidoc')
 
-const AttributeEntryRx = /^:([^:-][^:]*):(?: .*)?$/
-const BuiltInNamedEntities = { amp: '&', apos: "'", gt: '>', lt: '<', nbsp: ' ', quot: '"' }
-const CharRefRx = /&(?:([a-z][a-z]+\d{0,2})|#(?:(\d{2,6})|x([a-z\d]{2,5})));/g
-const DiscardAttributes = 'doctype leveloffset assembly-style underscore'.split(' ')
-const ReservedIdNames = 'content header footnotes footer footer-text premable toc toctitle'.split(' ')
+const ATTR_ENTRY_RX = /^:(!?[\p{Alpha}0-9_][^:]*):(?: |$)/u
+const BUILT_IN_NAMED_ENTITIES = { amp: '&', apos: "'", gt: '>', lt: '<', nbsp: ' ', quot: '"' }
+const CHAR_REF_RX = /&(?:([a-z][a-z]+\d{0,2})|#(?:(\d{2,6})|x([a-z\d]{2,5})));/g
+const DISCARD_ATTRIBUTE_NAMES = [
+  'doctype',
+  'leveloffset',
+  'assembly-header-attributes',
+  'assembly-navtitle',
+  'assembly-slug',
+  'assembly-style',
+  'underscore',
+]
+const { NAMED_ID_ATTR_RX } = require('./util/rx')
 
 function produceAssemblyFile (
   loadAsciiDoc,
@@ -23,39 +40,83 @@ function produceAssemblyFile (
 ) {
   const pagesByUrl = files.reduce((map, it) => (it.src.family === 'page' ? map.set(it.pub.url, it) : map), new Map())
   if (outline.urlType === 'internal' && !pagesByUrl.get(outline.url) && !(outline.items || []).length) return
-  const pagesInOutline = selectPagesInOutline(outline, pagesByUrl, componentVersion)
-  const navtitle = outline.content
+  const pagesInOutline = selectPagesInOutline(outline, pagesByUrl)
+  const { rootLevel, xmlIds } = assemblyModel
+  const idSeparators = {
+    prefix:
+      'assembler-idprefix' in asciidocConfig.attributes ? (asciidocConfig.attributes['assembler-idprefix'] ?? '') : '_',
+    scope: xmlIds ? '---' : ':::',
+    coordinate: xmlIds ? '----' : ':',
+    generateIdFromTitle: generateIdFromTitle.bind(
+      loadAsciiDoc(
+        { contents: Buffer.alloc(0), src: { family: 'page', relative: 'generate-id-from-title.adoc' } },
+        undefined,
+        asciidocConfig
+      )
+    ),
+  }
+  const { name: component, version } = componentVersion
+  asciidocConfig = prepareAsciiDocConfig(
+    contentCatalog,
+    { component, version },
+    pagesInOutline,
+    asciidocConfig,
+    assemblyModel,
+    idSeparators
+  )
   const buffer = mergeAsciiDoc(
     loadAsciiDoc,
     contentCatalog,
-    buildAsciiDocHeader(componentVersion, navtitle, assemblyModel),
+    buildAsciiDocHeader(componentVersion, outline.content, assemblyModel),
     componentVersion,
     outline,
     files,
     pagesInOutline,
+    idSeparators,
     asciidocConfig,
     mutableAttributes,
     assemblyModel
   )
-  const rootLevel = assemblyModel.rootLevel
-  const stem = rootLevel === 0 ? 'index' : generateSlug(navtitle)
-  const downloadStem = [componentVersion.name, componentVersion.version, rootLevel === 0 ? '' : stem]
-    .filter((it) => it)
-    .join('-')
+  const stem = buffer.slug ? sanitizeSlug(buffer.slug) : generateSlug(rootLevel === 0 ? 'index' : buffer.navtitle)
+  const downloadStem = [component, version, stem === 'index' ? '' : stem].filter((it) => it).join('-')
   return createAsciiDocFile(contentCatalog, {
     asciidoc: asciidocConfig,
     assembler: { assembled: pagesInOutline.assembled, downloadStem, rootLevel },
     contents: Buffer.from(buffer.join('\n') + '\n'),
-    src: {
-      component: componentVersion.name,
-      version: componentVersion.version,
-      module: 'ROOT',
-      family: 'export',
-      relative: stem + '.adoc',
-    },
+    src: { component, version, module: 'ROOT', family: 'export', relative: stem + '.adoc' },
   })
 }
 
+function prepareAsciiDocConfig (contentCatalog, ctx, pagesInOutline, asciidocConfig, assemblyModel, idSeparators) {
+  let attributesModified
+  const configShared = asciidocConfig.$shared
+  const sharedAttributes = asciidocConfig.attributes
+  if (!configShared) {
+    if (configShared == null) {
+      const assets = pagesInOutline.assembled.assets
+      for (const [name, val] of Object.entries(sharedAttributes)) {
+        if (!(typeof val === 'string' && ~val.indexOf(':'))) continue
+        let newVal
+        if (!name.endsWith('-image') || !(newVal = rewriteImageAttr(val, contentCatalog, assemblyModel, ctx, assets))) {
+          if (~(newVal = val).indexOf('image:')) {
+            newVal = rewriteInlineImages(newVal, contentCatalog, assemblyModel, ctx, assets)
+          }
+        }
+        if (newVal !== val) sharedAttributes[name] = newVal
+      }
+    }
+    for (const [name, val] of Object.entries(sharedAttributes)) {
+      if (!(typeof val === 'string' && ~val.indexOf(':'))) continue
+      if (~val.indexOf('xref:')) {
+        const newVal = rewriteXrefs(val, contentCatalog, assemblyModel, ctx, false, pagesInOutline, idSeparators)
+        if (newVal !== val) (attributesModified ??= {})[name] = newVal
+      }
+    }
+    if (configShared == null) Object.defineProperty(asciidocConfig, '$shared', { value: attributesModified == null })
+  }
+  return Object.assign({}, asciidocConfig, { attributes: Object.assign({}, sharedAttributes, attributesModified) })
+}
+
 function buildAsciiDocHeader (componentVersion, navtitle, assemblyModel) {
   const doctype = assemblyModel.doctype ?? 'book'
   const navtitlePlain = sanitize(navtitle)
@@ -63,30 +124,30 @@ function buildAsciiDocHeader (componentVersion, navtitle, assemblyModel) {
   let doctitle = navtitleAsciiDoc
   if (navtitlePlain !== componentVersion.title) doctitle = `${componentVersion.title}: ${doctitle}`
   const version = componentVersion.version === 'master' ? '' : componentVersion.version
-  return [
+  const displayVersion = componentVersion.displayVersion
+  const buffer = [
     `= ${doctitle}`,
-    ...(version ? [`:revnumber: ${version}`] : []),
+    ...(version ? [`:revnumber: ${displayVersion}`] : []),
     ...(doctype === 'article' ? [] : [`:doctype: ${doctype ?? 'book'}`]),
     ':underscore: _',
     // Q: should we pass these via the CLI so they cannot be modified?
     `:page-component-name: ${componentVersion.name}`,
     `:page-component-version:${version ? ' ' + version : ''}`,
     ':page-version: {page-component-version}',
-    `:page-component-display-version: ${componentVersion.displayVersion}`,
+    `:page-component-display-version: ${displayVersion}`,
     `:page-component-title: ${componentVersion.title}`,
   ]
+  return Object.assign(buffer, { navtitle })
 }
 
-function selectPagesInOutline (outlineEntry, pagesByUrl, componentVersion, accum) {
+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) {
-    if (page.src.component === componentVersion.name && page.src.version === componentVersion.version) {
-      accum.set(`${page.src.module === 'ROOT' ? '' : page.src.module + ':'}${page.src.relative}`, page)
-    }
-    accum.set(page.pub.url, page)
+    accum.set(createResourceKey(page.src), page)
+    accum.set(outlineEntry.url, page)
   }
-  for (const item of outlineEntry.items || []) selectPagesInOutline(item, pagesByUrl, componentVersion, accum)
+  for (const item of outlineEntry.items || []) selectPagesInOutline(item, pagesByUrl, accum)
   return accum
 }
 
@@ -98,6 +159,7 @@ function mergeAsciiDoc (
   outlineEntry,
   files,
   pagesInOutline,
+  idSeparators,
   asciidocConfig,
   mutableAttributes,
   assemblyModel,
@@ -106,68 +168,72 @@ function mergeAsciiDoc (
   supportsParts = false
 ) {
   // TODO: we could try to be smart about it and make sure the page with fragment is included at least once
-  if (outlineEntry.hash) return buffer
-  const { content: navtitle, items = [], unresolved, urlType, url } = outlineEntry
+  if (outlineEntry.hash) {
+    buffer.inBody ??= false
+    return buffer
+  }
+  let navtitle = outlineEntry.content
+  let navtitlePlain = sanitize(navtitle)
+  let navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
+  const { items = [], unresolved, urlType, url } = outlineEntry
+  const { doctype, filetype, linkReferenceStyle, pubRoot, siteRoot, logger } = 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 atDocumentRoot = !buffer.inBody
-  const atBookRoot = atDocumentRoot && !level && assemblyModel.doctype === 'book' && (supportsParts = true)
+  const isRootPage = page && atDocumentRoot && !level
+  const atBookRoot = atDocumentRoot && !level && doctype === 'book' && (supportsParts = true)
   const hasItems = items.length > 0
-  const navtitlePlain = sanitize(navtitle)
-  const navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
-  const siteUrl = ((val) => {
-    if (!val || val === '/') return ''
-    return val.charAt(val.length - 1) === '/' ? val.slice(0, val.length - 1) : val
-  })(asciidocConfig.attributes['primary-site-url'] || asciidocConfig.attributes['site-url'])
-  const idSeparator = assemblyModel.xmlIds ? '-' : ':'
-  const idScopeSeparator = idSeparator.repeat(3)
-  const idCoordinateSeparator = idSeparator === '-' ? '----' : idSeparator
-  // FIXME: ideally, resource ID would be stored in navigation so we can look up the page more efficiently
-  let page = urlType === 'internal' && !unresolved ? pagesInOutline.get(url) : undefined
-  if (page && pagesInOutline.assembled.pages.has(page)) page = undefined
-  if (page) {
-    let contents = page.src.contents
-    if (contents == null) return buffer
-    // NOTE: blank lines at top and bottom of document create mismatch when using line numbers to navigate source lines
-    // IMPORTANT: this must not leave behind lines the parser will drop!
-    // IDEA: another option is to capture initial lineno of reader and use as offset (but preseves those blank lines)
-    contents = Buffer.from(
-      contents
-        .toString()
-        .replace(/^(?:[ \t]*\r\n?|[ \t]*\n)+/, '')
-        .trimRight()
+  if (page && !assembled.pages.has(page)) {
+    const contents = page.src.contents
+    if (contents == null) {
+      buffer.inBody ??= false
+      return buffer
+    }
+    const { component, version, module: module_, relative, origin, mediaType } = page.src
+    const pageAsAsciiDoc = new page.constructor(
+      Object.assign({}, page, { contents: trimAsciiDoc(contents), mediaType })
     )
-    const { component, version, module: module_, relative, origin } = page.src
-    const topicPrefix = ~relative.indexOf('/') ? path.dirname(relative) + '/' : ''
-    const pageAsAsciiDoc = new page.constructor(Object.assign({}, page, { contents, mediaType: page.src.mediaType }))
     const doc = loadAsciiDoc(pageAsAsciiDoc, contentCatalog, asciidocConfig)
-    if (atDocumentRoot) {
-      const authors = doc.getAuthors()
-      if (authors.length) {
-        const authorLine = authors
-          .map((author) => {
-            const email = author.getEmail()
-            return email ? `${author.getName()} <${author.getEmail()}>` : author.getName()
-          })
-          .join('; ')
-        buffer.splice(1, 0, authorLine)
+    doc.logger = logger
+      ? Object.assign(doc.getLogger().$dup(), {
+          delegate: {
+            warn () {
+              return logger.warn.apply(logger, arguments)
+            },
+          },
+        })
+      : doc.getLogger()
+    doc.source_header_attributes ??= doc.parent.$to_h()
+    if (isRootPage && doc.hasAttribute('assembly-slug')) buffer.slug = doc.getAttribute('assembly-slug')
+    if (doc.hasAttribute('assembly-navtitle')) {
+      navtitleAsciiDoc = doc.getAttribute('assembly-navtitle')
+      navtitlePlain = sanitize((navtitle = doc.$apply_reftext_subs(navtitleAsciiDoc)))
+      if (buffer.inBody == null) {
+        buffer.navtitle = navtitle
+        // Q do we need to assert !level here?
+        if (assemblyModel.rootLevel) {
+          let doctitle = navtitleAsciiDoc
+          if (navtitlePlain !== componentVersion.title) doctitle = `${componentVersion.title}: ${doctitle}`
+          buffer[0] = `= ${doctitle}`
+        }
       }
     }
     // NOTE: in Antora, docname is relative src path from module without file extension
     const docname = doc.getAttribute('docname')
-    const docnameForId = docname.replace(/[/.]/g, '-')
-    const qualifyId = component !== componentVersion.name
-    let idScope = docnameForId
-    let idPrefix
-    if (qualifyId) {
-      idScope = [component, module_ === 'ROOT' ? '' : module_, idScope].join(idCoordinateSeparator)
-    } else if (module_ !== 'ROOT') {
-      idScope = module_ + idCoordinateSeparator + idScope
-    } else if (ReservedIdNames.includes(docnameForId)) {
-      idScope = idPrefix = idScope + idScopeSeparator
-    }
-    idPrefix ??= idScope + idScopeSeparator
+    const pageId = generateScopedId(page.src, componentVersion, idSeparators, filetype)
+    const pageIdLeader = pageId + idSeparators.scope
     let pageFragment = ''
     let pageRoles = ''
     let pageStyle = doc.getAttribute('assembly-style', '')
+    if (
+      !pageStyle &&
+      atBookRoot &&
+      doc.isAttribute('preface-title') &&
+      !('assembly-style' in doc.source_header_attributes.$$smap)
+    ) {
+      pageStyle = 'preface'
+    }
     let part
     if ((part = pageStyle === 'part')) {
       pageStyle = ''
@@ -179,7 +245,10 @@ function mergeAsciiDoc (
     let nextSectionLevel = 1
     const lines = doc.getSourceLines()
     const ignoreLines = []
-    buffer.inBody = true
+    if (!buffer.inBody) {
+      buffer.inBody = true
+      buffer.endHeaderIdx = buffer.length - 1
+    }
     buffer.push('')
     buffer.push(`:docname: ${docname}`)
     if (component !== lastComponentVersion.name) {
@@ -198,13 +267,68 @@ function mergeAsciiDoc (
     }
     buffer.push(`:page-module: ${module_}`)
     buffer.push(`:page-relative-src-path: ${relative}`)
-    //buffer.push(`:page-origin-type: ${origin.type}`)
     buffer.push(`:page-origin-url: ${origin.url}`)
     buffer.push(`:page-origin-start-path:${origin.startPath && ' '}${origin.startPath}`)
     buffer.push(`:page-origin-refname: ${origin.branch || origin.tag}`)
     buffer.push(`:page-origin-reftype: ${origin.branch ? 'branch' : 'tag'}`)
     buffer.push(`:page-origin-refhash: ${origin.worktree ? '(worktree)' : origin.refhash}`)
-    if (doc.hasHeader()) pageRoles = processDocumentHeader(doc, lines, buffer, ignoreLines)
+    if (doc.hasHeader()) {
+      for (const entry of processDocumentHeader(doc, lines, ignoreLines, isRootPage)) {
+        if (entry.type === 'author_line') {
+          buffer.splice(1, 0, entry.lines[0])
+          buffer.endHeaderIdx += 1
+        } else if (entry.type === 'attribute_entry') {
+          const name = entry.name
+          if (!entry.negated && !doc.isAttributeLocked(name)) {
+            let val, newVal
+            if (
+              name.endsWith('-image') &&
+              (val = doc.getAttribute(name)) &&
+              (newVal = rewriteImageAttr(val, contentCatalog, assemblyModel, page.src, assembled.assets))
+            ) {
+              if (newVal !== val) entry.lines = [`:${name}: ${newVal}`]
+            } else if (~(val = entry.lines.join('\n').slice(name.length + 3)).indexOf(':')) {
+              newVal = val
+              if (~newVal.indexOf('image:')) {
+                newVal = rewriteInlineImages(
+                  newVal,
+                  contentCatalog,
+                  assemblyModel,
+                  page.src,
+                  assembled.assets,
+                  false,
+                  doc
+                )
+              }
+              if (~newVal.indexOf('xref:')) {
+                newVal = rewriteXrefs(
+                  newVal,
+                  contentCatalog,
+                  assemblyModel,
+                  page.src,
+                  false,
+                  pagesInOutline,
+                  idSeparators,
+                  pageIdLeader,
+                  doc,
+                  { file: relative, lineno: entry.lineno }
+                )
+              }
+              if (newVal !== val) entry.lines = `:${entry.name}: ${newVal}`.split('\n')
+            }
+          }
+          if (entry.promote) {
+            buffer.splice(buffer.endHeaderIdx + 1, 0, ...entry.lines)
+            buffer.endHeaderIdx += entry.lines.length
+          } else {
+            buffer.push(...entry.lines)
+          }
+        } else {
+          buffer.push(...entry.lines)
+        }
+      }
+      pageRoles = doc.getRoles().reduce((accum, role) => `${accum}.${role}`, '')
+    }
     let heading
     if (pageStyle && (part && level === 1 ? (level = 0) : level) === 0) {
       let htitleAsciiDoc = navtitleAsciiDoc
@@ -221,10 +345,10 @@ function mergeAsciiDoc (
         assemblyModel = Object.assign({}, assemblyModel, { sectionMergeStrategy: 'discrete' })
       } else {
         if (atDocumentRoot) {
-          pageFragment = `#${idPrefix}${doc.getId() ?? pageStyle}`
-          buffer.unshift(`[#${idScope}]`)
+          pageFragment = `#${pageIdLeader}${doc.getId() ?? pageStyle}`
+          buffer.unshift(`[#${pageId}]`)
         } else {
-          pageFragment = `#${idScope}`
+          pageFragment = `#${pageId}`
         }
         heading = { title: htitleAsciiDoc, level: part ? 1 : 2 }
         nextSectionLevel++
@@ -233,7 +357,7 @@ function mergeAsciiDoc (
       if (atDocumentRoot && navtitlePlain === componentVersion.title) {
         level--
       } else {
-        pageFragment = `#${idScope}`
+        pageFragment = `#${pageId}`
         if (part && level === 1) level--
         if ((heading = { title: navtitleAsciiDoc, level: level + 1 }).level > 6) {
           Object.assign(heading, { level: 6, style: `discrete.h${heading.level}` })
@@ -244,7 +368,7 @@ function mergeAsciiDoc (
       buffer.push(`[${heading.style ?? pageStyle}${pageFragment}${pageRoles}]`)
       buffer.push(`${'='.repeat(heading.level)} ${heading.title}`)
     } else if (atDocumentRoot) {
-      buffer.unshift(`[#${idScope}]`)
+      buffer.unshift(`[#${pageId}]`)
     }
     let enclosed
     if (assemblyModel.sectionMergeStrategy === 'enclose' && hasItems && doc.hasSections()) {
@@ -254,28 +378,18 @@ function mergeAsciiDoc (
       //if (overviewTitle === navtitle) overviewTitle = doc.getAttribute('overview-title', 'Overview')
       const overviewTitle = doc.getAttribute('overview-title', 'Overview')
       buffer.push('')
-      // NOTE: try to toggle sectids; otherwise, fallback to globally unique synthetic ID
-      let toggleSectids, syntheticId
-      if (doc.isAttribute('sectids')) {
-        if (doc.isAttributeLocked('sectids')) {
-          syntheticId = `__object-id-${getObjectId(outlineEntry)}`
-        } else {
-          buffer.push(':!sectids:')
-          toggleSectids = true
-        }
-      }
+      const syntheticId = idSeparators.generateIdFromTitle(navtitleAsciiDoc, idSeparators)
       let hlevel = level + 2
       if (hlevel > 6) {
         const blockStyle = `discrete.h${hlevel}`
         hlevel = 6
-        buffer.push(syntheticId ? `[${blockStyle}#${syntheticId}]` : `[${blockStyle}]`)
-      } else if (syntheticId) {
+        buffer.push(`[${blockStyle}#${syntheticId}]`)
+      } else {
         buffer.push(`[#${syntheticId}]`)
       }
       buffer.push(`${'='.repeat(hlevel)} ${overviewTitle}`)
-      if (toggleSectids) buffer.push(':sectids:')
     }
-    pagesInOutline.assembled.pages.set(page, pageFragment)
+    assembled.pages.set(page, pageFragment)
     if (doc.hasSections()) {
       fixSectionLevels(doc.getSections(), atBookRoot && !pageStyle ? undefined : nextSectionLevel)
     }
@@ -349,7 +463,7 @@ function mergeAsciiDoc (
       if (
         line.charAt() === ':' &&
         ~line.indexOf(':', 2) &&
-        (line.match(AttributeEntryRx) || ['', ''])[1].replace('!', '') === 'leveloffset'
+        (line.match(ATTR_ENTRY_RX) || ['', ''])[1].replace('!', '') === 'leveloffset'
       ) {
         if (lines[idx - 1] === '') lines[idx - 1] = undefined
         lines[idx] = undefined
@@ -361,96 +475,31 @@ function mergeAsciiDoc (
           if (!refs['$key?'](refid) && (~refid.indexOf(' ') || refid.toLowerCase() !== refid)) {
             if ((refid = doc.$resolve_id(refid))['$nil?']()) return m
           }
-          return `<<${idPrefix}${refid}${text ? ',' + text : ''}>>`
+          return `<<${pageIdLeader}${refid}${text ? ',' + text : ''}>>`
         })
       }
       // NOTE: the next check takes care of inline and block anchors
       if (~line.indexOf('[[')) {
-        line = line.replace(/\[\[([\p{Alpha}_:][\p{Alpha}0-9_\-:.]*)(|, *.+?)\]\]/gu, `[[${idPrefix}$1$2]]`)
-      }
-      if (~line.indexOf('xref:')) {
-        // Q: should we allow : as first character of target?
-        line = line.replace(/(?<![\\+])xref:((?:\.\/)?[\p{Alpha}0-9_/.{#].*?)\[(|.*?[^\\])\]/gu, (m, target, text) => {
-          let pagePart, fragment, targetPage
-          const hashIdx = target.indexOf('#')
-          if (~hashIdx) {
-            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')) {
-            pagePart = target
-            fragment = ''
-          } else {
-            fragment = target
-          }
-          if (!pagePart) {
-            // Q: should we validate the internal ID here?
-            return text && ~text.indexOf('=')
-              ? `xref:${idPrefix}${fragment}[${text}]`
-              : `<<${idPrefix}${fragment}${text ? ',' + text.replace(/\\]/g, ']') : ''}>>`
-          }
-          if (~pagePart.indexOf('@') || /:.*:/.test(pagePart)) {
-            if (siteUrl && (targetPage = contentCatalog.resolvePage(pagePart, page.src)) && targetPage.out) {
-              text ||= targetPage.asciidoc?.xreftext || target
-              return `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
-            }
-            // TODO: handle unresolved page better
-            return m
-          }
-          let targetModule
-          const colonIdx = pagePart.indexOf(':')
-          if (~colonIdx) {
-            targetModule = pagePart.slice(0, colonIdx)
-            pagePart = pagePart.slice(colonIdx + 1)
-          } else {
-            targetModule = module_
-          }
-          if (pagePart.startsWith('./')) pagePart = topicPrefix + pagePart.slice(2)
-          const pageResourceRef = targetModule === 'ROOT' ? pagePart : `${targetModule}:${pagePart}`
-          if (!(targetPage = pagesInOutline.get(pageResourceRef))) {
-            if (siteUrl && (targetPage = contentCatalog.resolvePage(pageResourceRef, page.src)) && targetPage.out) {
-              text ||= targetPage.asciidoc?.xreftext || target
-              return `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
-            }
-            // TODO: handle unresolved page better
-            return m
-          }
-          if (targetModule !== 'ROOT') pagePart = `${targetModule}${idCoordinateSeparator}${pagePart}`
-          pagePart = pagePart.replace(/\.adoc$/, '').replace(/[/.]/g, '-')
-          const refid = fragment
-            ? `${pagePart}${idScopeSeparator}${fragment}`
-            : pagePart + (ReservedIdNames.includes(pagePart) ? idScopeSeparator : '')
-          return `<<${refid}${text && text !== targetPage.title ? ',' + text.replace(/\\]/g, ']') : ''}>>`
+        line = line.replace(/\[\[([\p{Alpha}_:][\p{Alpha}0-9_\-:.]*)(|, *.+?)\]\]/gu, (_, refid, text) => {
+          return `[[${pageIdLeader}${refid}${text}]]`
         })
       }
-      if (~line.indexOf('link:{attachmentsdir}/')) {
-        line = line.replace(/(?<![\\+])link:\{attachmentsdir\}\/([^\s[]+)\[(|.*?[^\\])\]/g, (m, relative, text) => {
-          const attachment =
-            siteUrl &&
-            contentCatalog.getById({
-              component: componentVersion.name,
-              version: componentVersion.version,
-              module: module_,
-              family: 'attachment',
-              relative,
-            })
-          // TODO: handle unresolved attachment page
-          return attachment?.out ? `${siteUrl}${attachment.pub.url.replace(/_/g, '{underscore}')}[${text}]` : m
-        })
+      if (~line.indexOf('xref:')) {
+        line = rewriteXrefs(
+          line,
+          contentCatalog,
+          assemblyModel,
+          page.src,
+          true,
+          pagesInOutline,
+          idSeparators,
+          pageIdLeader,
+          doc,
+          { file: relative, lineno: idx + 1 }
+        )
       }
       if (~line.indexOf('image:') && !line.startsWith('image::')) {
-        line = line.replace(/(?<![\\+])image:([^:\s[](?:[^[]*[^\s[])?)\[([^\]]*)\]/g, (m, target, attrlist) => {
-          if (isResourceSpec(target)) {
-            const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
-            // TODO: handle (or report) unresolved image better
-            if (image?.out) {
-              pagesInOutline.assembled.assets.add(image)
-              return `image:${image.out.path.replace(/_/g, '{underscore}')}[${attrlist}]`
-            }
-          }
-          return m
-        })
+        line = rewriteInlineImages(line, contentCatalog, assemblyModel, page.src, assembled.assets, true, doc)
       }
       lines[idx] = line
     }
@@ -476,7 +525,7 @@ function mergeAsciiDoc (
           return '='.repeat(targetMarkerLength) + ' ' + rest
         })
         // NOTE: ID will be undefined if sectids are turned off
-        if (block.getId()) rewriteStyleAttribute(block, lines, idx, idPrefix, blockStyle)
+        if (block.getId()) rewriteStyleAttribute(block, lines, idx, pageIdLeader, blockStyle)
       } else {
         if (context === 'image') {
           let line = lines[idx] || ''
@@ -495,31 +544,24 @@ function mergeAsciiDoc (
               imageMacroOffset = -1
             }
           }
-          if (imageMacroOffset >= 0) {
+          if (~imageMacroOffset) {
             const target = block.getAttribute('target')
-            if (isResourceSpec(target)) {
-              const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
-              // FIXME: handle (or report) case when image is not resolved
-              if (image?.out) {
-                const boxedAttrlist = line.slice(line.indexOf('['))
-                pagesInOutline.assembled.assets.add(image)
-                lines[idx] = `${prefix}image::${image.out.path}${boxedAttrlist}`
-              }
-            }
+            const newTarget = rewriteImageRef(target, contentCatalog, assemblyModel, page.src, assembled.assets)
+            if (newTarget) lines[idx] = `${prefix}image::${newTarget}${line.slice(line.indexOf('['))}`
             lastImageMacroAt = [idx, imageMacroOffset]
           }
         } else if (context === 'document' && block.hasHeader()) {
           // nested document
           idx = (block.getHeader().getLineNumber() || idx + 1) - 1
         }
-        if (block.getId()) rewriteStyleAttribute(block, lines, idx, idPrefix)
+        if (block.getId()) rewriteStyleAttribute(block, lines, idx, pageIdLeader)
       }
     })
     safePush(
       buffer,
       lines.filter((it) => it !== undefined)
     )
-    const attributeEntries = Object.entries(doc.source_header_attributes?.$$smap || {})
+    const attributeEntries = Object.entries(doc.source_header_attributes.$$smap)
     if (attributeEntries.length) {
       const resolvedAttributeEntries = attributeEntries.reduce(
         (accum, [name, val]) => {
@@ -531,7 +573,7 @@ function mergeAsciiDoc (
             } else if (val !== initialVal) {
               accum.push(`:${name}:${initialVal ? ' ' + initialVal : ''}`)
             }
-          } else if (!(val == null || doc.isAttributeLocked(name) || DiscardAttributes.includes(name))) {
+          } else if (!(val == null || doc.isAttributeLocked(name) || DISCARD_ATTRIBUTE_NAMES.includes(name))) {
             accum.push(`:!${name}:`)
           }
           return accum
@@ -542,43 +584,36 @@ function mergeAsciiDoc (
     }
   } else if (level) {
     if (atDocumentRoot && navtitlePlain === componentVersion.title) {
+      buffer.inBody ??= false
       level--
     } else {
       buffer.inBody = true
       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 {
-          syntheticId = `__object-id-${global.Opal.hash(outlineEntry).$object_id()}`
-        }
-      }
+      const syntheticId = idSeparators.generateIdFromTitle(navtitleAsciiDoc, idSeparators)
       let sectionTitle = navtitleAsciiDoc
       if (urlType === 'external') {
         sectionTitle = `${url}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
-      } else if (urlType === 'internal' && !unresolved && siteUrl) {
+      } else if (urlType === 'internal' && !unresolved) {
         const resource = files.find((it) => it.pub.url === url)
-        if (resource) sectionTitle = `${siteUrl}${resource.pub.url}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+        if (resource) {
+          if (resource.src.family === 'page' && pagesInOutline.has(resource.pub.url)) {
+            const refid = generateScopedId(resource.src, componentVersion, idSeparators, filetype, true)
+            sectionTitle = `xref:${refid}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+          } else if (siteRoot) {
+            sectionTitle = `${resolveLinkTarget(resource, siteRoot, pubRoot, linkReferenceStyle, true)}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+          }
+        }
       }
       let hlevel = level + 1
       if (hlevel > 6) {
         hlevel = 6
-        buffer.push(syntheticId ? `[discrete#${syntheticId}]` : '[discrete]')
-      } else if (syntheticId) {
+        buffer.push(`[discrete#${syntheticId}]`)
+      } else {
         buffer.push(`[#${syntheticId}]`)
       }
       buffer.push(`${'='.repeat(hlevel)} ${sectionTitle}`)
-      if (toggleSectids) buffer.push(':sectids:')
     }
   }
-
   if (hasItems) {
     const nextLevel = level + 1
     // NOTE: drop first child if same as parent; should we keep if content is different?
@@ -594,6 +629,7 @@ function mergeAsciiDoc (
         item,
         files,
         pagesInOutline,
+        idSeparators,
         asciidocConfig,
         mutableAttributes,
         assemblyModel,
@@ -606,11 +642,32 @@ function mergeAsciiDoc (
   return buffer
 }
 
-function processDocumentHeader (doc, lines, buffer, ignoreLines) {
+function processDocumentHeader (doc, lines, ignoreLines, isRootPage) {
+  const entries = []
+  let assemblyHeaderAttributes = isRootPage && doc.getAttribute('assembly-header-attributes', '%authors')
+  assemblyHeaderAttributes = new Set(assemblyHeaderAttributes ? assemblyHeaderAttributes.split(/, */) : undefined)
+  if (assemblyHeaderAttributes.size) {
+    if (assemblyHeaderAttributes.has('%authors')) {
+      const authors = doc.getAuthors()
+      if (authors.length) {
+        entries.push({
+          type: 'author_line',
+          promote: true,
+          lines: [
+            authors
+              .map((author) => (author.getEmail() ? `${author.getName()} <${author.getEmail()}>` : author.getName()))
+              .join('; '),
+          ],
+        })
+      }
+      assemblyHeaderAttributes.delete('%authors')
+    }
+    const headerAttributes = doc.source_header_attributes
+    for (const name of assemblyHeaderAttributes) headerAttributes.$delete(name)
+  }
   const doctitleIdx = doc.getHeader().getLineNumber() - 1
   const end = doc.getBlocks()[0]?.getLineNumber() ?? lines.length
-  let belowDoctitle
-  let open
+  let belowDoctitle, current, open
   const implicitLines = []
   for (let idx = 0; idx < end; idx++) {
     if (idx === doctitleIdx) {
@@ -621,35 +678,51 @@ function processDocumentHeader (doc, lines, buffer, ignoreLines) {
     }
     const line = lines[idx]
     if (open === ':' || open === '-:') {
-      if (line) {
-        if (open === ':') buffer.push(line)
-        if (!line.endsWith(' \\')) open = undefined
-      } else {
-        open = undefined
-      }
+      if (open === ':') current.lines.push(line)
+      if (!line || !line.endsWith(' \\')) current = open = undefined
     } else if (line) {
-      const chr0 = line.charAt()
       let attributeEntryMatch
+      const chr0 = line.charAt()
       if (chr0 === '/' && line.charAt(1) === '/') {
-        if (line.startsWith('////')) {
-          open = open ? (open === line ? undefined : open) : line
-        } else if (belowDoctitle && !open && line.charAt(2) === '/') {
+        if (line.startsWith('////') && line === '/'.repeat(line.length)) {
+          if (open) {
+            current.lines.push(line)
+            if (open === line) current = open = undefined
+          } else {
+            entries.push((current = { type: 'block_comment', lines: [(open = line)] }))
+          }
+        } else if (open) {
+          current.lines.push(line)
+        } else if (belowDoctitle && line.charAt(2) === '/') {
           break
+        } else {
+          entries.push({ type: 'line_comment', lines: [line] })
+          current = undefined
         }
-        buffer.push(line)
       } else if (open) {
-        buffer.push(line)
-      } else if (chr0 === ':' && ~line.indexOf(':', 2) && (attributeEntryMatch = line.match(AttributeEntryRx))) {
-        const attributeName = attributeEntryMatch[1].replace('!', '')
-        if (DiscardAttributes.includes(attributeName)) {
-          if (line.endsWith(' \\')) open = '-:'
+        current.lines.push(line)
+      } else if (chr0 === ':' && ~line.indexOf(':', 2) && (attributeEntryMatch = line.match(ATTR_ENTRY_RX))) {
+        let name = attributeEntryMatch[1]
+        const negated = name.charAt() === '!' || name.charAt(name.length - 1) === '!'
+        if (negated) name = name.replace('!', '')
+        if (DISCARD_ATTRIBUTE_NAMES.includes(name)) {
+          if (line.endsWith(' \\')) open = '-:' // disallow value continuation
         } else {
           if (line.endsWith(' \\')) open = ':'
-          buffer.push(line)
+          entries.push((current = { type: 'attribute_entry', name, negated, lines: [line], lineno: idx + 1 }))
+          if (assemblyHeaderAttributes.has(name)) current.promote = true
         }
       } else if (belowDoctitle) {
         if (implicitLines.length === 2 || !/[\p{Alpha}0-9]/u.test(chr0)) break
         implicitLines.push(line)
+      } else if (chr0 === '[' && line.charAt(line.length - 1) === ']') {
+        current = undefined
+        const attrlist = line
+          .slice(1, -1)
+          .trim()
+          .replace(/(?:^\w[\w-]*(?!=|[\w-]))?([#.]\w[\w-]*)*/, '')
+          .replace(NAMED_ID_ATTR_RX, '')
+        if (attrlist) entries.push({ type: 'attrlist', lines: ['[' + attrlist + ']'] })
       }
     } else if (belowDoctitle) {
       break
@@ -657,25 +730,27 @@ function processDocumentHeader (doc, lines, buffer, ignoreLines) {
     lines[idx] = undefined
     ignoreLines.push(idx)
   }
-  return doc
-    .getRoles()
-    .map((role) => '.' + role)
-    .join('')
+  return entries
 }
 
-function generateSlug (title) {
-  return title
+function generateSlug (string) {
+  if (string === 'index') return string
+  return string
     .toLowerCase()
     .replace(/<[^>]+>/g, '')
-    .replace(CharRefRx, (_, name, dec, hex) => {
-      if (name) return BuiltInNamedEntities[name] ?? '?'
+    .replace(CHAR_REF_RX, (_, name, dec, hex) => {
+      if (name) return BUILT_IN_NAMED_ENTITIES[name] ?? '?'
       return String.fromCharCode(dec ? parseInt(dec, 10) : parseInt(hex, 16))
     })
     .replace(/[\x27\u2019]/g, '')
-    .replace(/[^\p{Alpha}0-9\-]/gu, '-')
+    .replace(/[^\p{Alpha}0-9-]/gu, '-')
     .replace(/^-+|-+$|(-)-+/g, '$1')
 }
 
+function sanitizeSlug (slug) {
+  return slug.replace(/ /g, '-').replace(/[^\p{Alpha}0-9_.-]/gu, '-')
+}
+
 function fixSectionLevels (sections, expectedLevel) {
   sections.forEach((sect) => {
     const forceLevel = expectedLevel ?? Math.min(1, sect.getLevel())
@@ -684,62 +759,16 @@ function fixSectionLevels (sections, expectedLevel) {
   })
 }
 
-function rewriteStyleAttribute (block, lines, idx, idPrefix, replacementStyle = '') {
-  let prevLine = lines[idx - 1]
-  const char0 = prevLine?.charAt()
-  if (char0) {
-    if (
-      (char0 === '.' && /^\.\.?[^ \t.]/.test(prevLine)) ||
-      (char0 === '[' &&
-        prevLine.charAt(1) === '[' &&
-        /^\[\[(?:|[\p{Alpha}_:][\p{Alpha}0-9_\-:.]*(?:, *.+)?)\]\]$/u.test(prevLine))
-    ) {
-      return rewriteStyleAttribute(block, lines, idx - 1, idPrefix, replacementStyle)
-    }
-  }
-  let cellSpec
-  if (
-    char0 &&
-    (char0 === '[' || (block.getDocument().isNested() && (cellSpec = prevLine.match(/^([^[|]*)\| *(\[.+)/)))) &&
-    prevLine.charAt(prevLine.length - 1) === ']'
-  ) {
-    if (cellSpec) {
-      prevLine = cellSpec[2]
-      cellSpec = cellSpec[1]
-    }
-    let rawStyle
-    const commaIdx = prevLine.indexOf(',')
-    if (~commaIdx) {
-      rawStyle = prevLine.slice(1, commaIdx)
-      if (~rawStyle.indexOf('=')) rawStyle = undefined
-    } else if (!~prevLine.indexOf('=')) {
-      rawStyle = prevLine.slice(1, prevLine.length - 1)
-    }
-    if (rawStyle) {
-      if (~rawStyle.indexOf('#')) {
-        prevLine = prevLine.replace(/#[^.%,\]]+/, `#${idPrefix}${block.getId()}`)
-        if (replacementStyle) prevLine = prevLine.replace(/^[^#.%,\]]+/, `[${replacementStyle}`)
-      } else {
-        prevLine = `[${
-          replacementStyle ? rawStyle.replace(/^[^.%]*/, replacementStyle) : rawStyle
-        }#${idPrefix}${block.getId()}${prevLine.slice(rawStyle.length + 1)}`
-      }
-    } else {
-      prevLine = `[${replacementStyle}#${idPrefix}${block.getId()}${rawStyle == null ? ',' : ''}${prevLine.slice(1)}`
-    }
-    if (cellSpec) prevLine = `${cellSpec}|${prevLine}`
-    lines[idx - 1] = prevLine
-  } else {
-    lines.splice(idx, 0, `[${replacementStyle}#${idPrefix}${block.getId()}]`)
-  }
-}
-
-function isResourceSpec (str) {
-  return !(~str.indexOf(':') && (~str.indexOf('://') || (str.startsWith('data:') && ~str.indexOf(','))))
-}
-
-function getObjectId (obj) {
-  return global.Opal.uid()
+// NOTE: blank lines at top and bottom of document create mismatch when using line numbers to navigate source lines
+// IMPORTANT: this must not leave behind lines the parser will drop!
+// IDEA: another option is to capture initial lineno of reader and use as offset (but preseves those blank lines)
+function trimAsciiDoc (buffer) {
+  return Buffer.from(
+    buffer
+      .toString()
+      .replace(/^(?:[ \t]*\r\n?|[ \t]*\n)+/, '')
+      .trimRight()
+  )
 }
 
 function safePush (onto, entries) {
@@ -752,4 +781,11 @@ function safePush (onto, entries) {
   }
 }
 
+function generateIdFromTitle (titleAsciiDoc, idSeparators) {
+  const Section = this.$class().$const_get('::Asciidoctor::Section')
+  const baseId = Section.$generate_id(titleAsciiDoc, this)
+  this.getCatalog().refs['$[]='](baseId, true)
+  return `_${idSeparators.coordinate}${baseId}`
+}
+
 module.exports = produceAssemblyFile