@antora/assembler 1.0.0-beta.9 → 1.0.0-rc.10

package/lib/produce-assembly-file.js

@@ -1,15 +1,38 @@
 '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 toHash = require('./util/to-hash')
 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-navtitle 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 = [
+  'assembly-doctype',
+  'assembly-header-attributes',
+  'assembly-overview-title',
+  'assembly-navtitle',
+  'assembly-root-title',
+  'assembly-slug',
+  'assembly-style',
+  'doctype',
+  'leveloffset',
+  'page-aliases',
+  'preface-title',
+  'underscore',
+]
+const { NAMED_ID_ATTR_RX } = require('./util/rx')
+const ASSEMBLY_STYLE_SUPPORTS_SECTIONS = ['abstract', 'appendix', 'part', 'preface', 'section']
 
 function produceAssemblyFile (
   loadAsciiDoc,
@@ -22,185 +45,318 @@ 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, componentVersion)
-  const buffer = mergeAsciiDoc(
+  const pagesInOutline = selectPagesInOutline(outline, pagesByUrl)
+  if (outline.urlType === 'internal' && !pagesByUrl.has(outline.pathname) && !outline.items?.length) return
+  const { name: component, version } = componentVersion
+  const { rootLevel, xmlIds } = assemblyModel
+  const scratchDoc = loadAsciiDoc(
+    {
+      contents: Buffer.alloc(0),
+      src: { component, version, module: 'ROOT', family: 'page', relative: '_.adoc', path: '_.adoc' },
+    },
+    undefined,
+    Object.assign({}, asciidocConfig, { antoraResourceRefs: false, extensions: [] })
+  )
+  const idSeparators = {
+    prefix:
+      'assembler-idprefix' in asciidocConfig.attributes ? (asciidocConfig.attributes['assembler-idprefix'] ?? '') : '_',
+    scope: xmlIds ? '---' : ':::',
+    coordinate: xmlIds ? '----' : ':',
+    generateIdFromTitle: generateIdFromTitle.bind(scratchDoc),
+  }
+  asciidocConfig = prepareAsciiDocConfig(
+    contentCatalog,
+    { component, version },
+    pagesInOutline,
+    asciidocConfig,
+    assemblyModel,
+    idSeparators,
+    scratchDoc
+  )
+  const builder = buildAssemblyHeader(componentVersion, outline.content, assemblyModel)
+  mergeAsciiDoc(
     loadAsciiDoc,
     contentCatalog,
-    buildAsciiDocHeader(componentVersion, outline.content, assemblyModel),
+    builder,
     componentVersion,
     outline,
     files,
     pagesInOutline,
+    idSeparators,
     asciidocConfig,
     mutableAttributes,
     assemblyModel
   )
-  const rootLevel = assemblyModel.rootLevel
-  const stem = rootLevel === 0 ? 'index' : generateSlug(buffer.navtitle)
-  const downloadStem = [componentVersion.name, componentVersion.version, rootLevel === 0 ? '' : stem]
-    .filter((it) => it)
-    .join('-')
-  return createAsciiDocFile(contentCatalog, {
+  const stem =
+    (builder.slug ? sanitizeSlug(builder.slug) : generateSlug(rootLevel === 0 ? 'index' : builder.baseDoctitle)) ||
+    'export-' + (assemblyModel.stemSeq = (assemblyModel.exportSeq ?? 0) + 1)
+  const downloadStem = [component, version, stem === 'index' ? '' : stem].filter((it) => it).join('-')
+  const file = contentCatalog.createFile({
     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',
-    },
+    contents: builder.serialize(),
+    src: { component, version, componentVersion, module: 'ROOT', family: 'export', relative: stem + '.adoc' },
+    pub: false,
   })
+  file.path = file.out.path // use out path as path so assets can be published to same hierarchy
+  delete file.out
+  return file
 }
 
-function buildAsciiDocHeader (componentVersion, navtitle, assemblyModel) {
-  const doctype = assemblyModel.doctype ?? 'book'
-  const navtitlePlain = sanitize(navtitle)
+function prepareAsciiDocConfig (contentCatalog, ctx, pagesInOutline, asciidocConfig, assemblyModel, idSeparators, doc) {
+  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 (!(val?.constructor === 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 (!(val?.constructor === String && ~val.indexOf(':'))) continue
+      if (~val.indexOf('xref:')) {
+        const newVal = rewriteXrefs(
+          val,
+          contentCatalog,
+          assemblyModel,
+          ctx,
+          false,
+          pagesInOutline,
+          idSeparators,
+          null,
+          doc
+        )
+        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 buildAssemblyHeader (componentVersion, navtitle, assemblyModel) {
+  const { name: componentName, version, displayVersion, title } = componentVersion
   const navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
-  let doctitle = navtitleAsciiDoc
-  if (navtitlePlain !== componentVersion.title) doctitle = `${componentVersion.title}: ${doctitle}`
-  const version = componentVersion.version === 'master' ? '' : componentVersion.version
-  const buffer = [
-    `= ${doctitle}`,
-    ...(version ? [`:revnumber: ${version}`] : []),
-    ...(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-title: ${componentVersion.title}`,
-  ]
-  return Object.assign(buffer, { navtitle })
+  const navtitlePlain = sanitize(navtitle)
+  const doctitleQualifier = assemblyModel.rootLevel === 0 ? '' : title
+  const versioned = !!(version && version !== 'master')
+  return {
+    header: [
+      `= ${doctitleQualifier && doctitleQualifier !== navtitlePlain ? doctitleQualifier + ': ' : ''}${navtitleAsciiDoc}`,
+      ...(versioned ? [`:revnumber: ${displayVersion}`] : []),
+      `:doctype: ${(assemblyModel.doctype ??= 'book')}`,
+      ':underscore: _',
+      `:page-component-name: ${componentName}`,
+      `:page-component-version:${versioned ? ' ' + version : ''}`,
+      ':page-version: {page-component-version}',
+      `:page-component-display-version: ${displayVersion}`,
+      `:page-component-title: ${title}`,
+    ],
+    currentComponentVersion: componentVersion,
+    doctitleQualifier,
+    baseDoctitle: navtitle,
+    baseDoctitlePlain: navtitlePlain,
+    setAuthor (author) {
+      this.header.splice(1, 0, author)
+    },
+    setDoctitle (doctitle, doctitleAsciiDoc, doctitlePlain) {
+      this.baseDoctitle = doctitle
+      this.baseDoctitlePlain = doctitlePlain
+      const qualifyDoctitle = this.doctitleQualifier ? this.doctitleQualifier !== doctitlePlain : false
+      this.header[0] = `= ${qualifyDoctitle ? this.doctitleQualifier + ': ' : ''}${doctitleAsciiDoc}`
+    },
+    matchesDoctitle (candidate) {
+      return candidate === this.baseDoctitlePlain
+    },
+    setDoctype (doctype) {
+      this.header[this.header.findIndex((line) => line.startsWith(':doctype: '))] = `:doctype: ${doctype}`
+    },
+    setDocid (docid) {
+      this.header.unshift(`[#${docid}]`)
+    },
+    serialize () {
+      const normalizedHeader = this.header.filter((it) => it !== ':doctype: article')
+      return this.body
+        ? Buffer.from(normalizedHeader.join('\n') + '\n\n' + this.body.join('\n') + '\n')
+        : Buffer.from(normalizedHeader.join('\n') + '\n')
+    },
+  }
 }
 
-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)
+  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)
     }
-    accum.set(page.pub.url, page)
   }
-  for (const item of outlineEntry.items || []) selectPagesInOutline(item, pagesByUrl, componentVersion, accum)
+  for (const item of items) selectPagesInOutline(item, pagesByUrl, accum)
   return accum
 }
 
 function mergeAsciiDoc (
   loadAsciiDoc,
   contentCatalog,
-  buffer,
+  builder,
   componentVersion,
   outlineEntry,
   files,
   pagesInOutline,
+  idSeparators,
   asciidocConfig,
   mutableAttributes,
   assemblyModel,
-  lastComponentVersion = componentVersion,
   level = 0,
   supportsParts = false
 ) {
+  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 (outlineEntry.hash) {
-    buffer.inBody ??= false
-    return buffer
+  if (roles.includes('site-only') || (urlType === 'external' && !URL.canParse(url))) {
+    builder.body ??= []
+    return builder
   }
-  let navtitle = outlineEntry.content
-  let navtitlePlain = sanitize(navtitle)
-  let navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
-  const { items = [], unresolved, urlType, url } = outlineEntry
-  const {
-    doctype,
-    filetype,
-    embedReferenceStyle: embedRefStyle,
-    linkReferenceStyle: linkRefStyle,
-    outDirname,
-    siteRoot,
-    xmlIds,
-  } = assemblyModel
+  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 && doctype === 'book' && (supportsParts = true)
+  const page = urlType === 'internal' && !unresolved ? pagesInOutline.get(pathname) : undefined
+  let navtitle = outlineEntry.navtitle ?? (page && hash ? page.asciidoc.navtitle : outlineEntry.content)
+  let navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
+  let navtitlePlain = sanitize(navtitle)
+  const { doctype, filetype, linkReferenceStyle, pubRoot, siteRoot, logger, rootPageStyle } = assemblyModel
+  let sectionMergeStrategy = assemblyModel.sectionMergeStrategy
+  const atStartOfBody = !builder.body?.length
+  const isRootEntry = atStartOfBody && !level
+  let atBookRoot = isRootEntry && doctype === 'book' && (supportsParts = true)
   const hasItems = items.length > 0
-  const pubRoot = outDirname ? '/' + outDirname : ''
-  const idSeparator = xmlIds ? '-' : ':'
-  const idScopeSeparator = idSeparator.repeat(3)
-  const idCoordinateSeparator = idSeparator === '-' ? '----' : idSeparator
-  if (page && !pagesInOutline.assembled.pages.has(page)) {
+  if (page && !assembled.pages.has(page)) {
     const contents = page.src.contents
     if (contents == null) {
-      buffer.inBody ??= false
-      return buffer
+      builder.body ??= []
+      return builder
     }
-    const { component, version, module: module_, relative, origin, mediaType } = page.src
-    const topicPrefix = ~relative.indexOf('/') ? path.dirname(relative) + '/' : ''
     const pageAsAsciiDoc = new page.constructor(
-      Object.assign({}, page, { contents: trimAsciiDoc(contents), mediaType })
+      Object.assign({}, page, { contents: Buffer.from(contents.toString().trimEnd()), mediaType: page.src.mediaType })
     )
     const doc = loadAsciiDoc(pageAsAsciiDoc, contentCatalog, asciidocConfig)
-    if (doc.hasAttribute('assembly-navtitle')) {
+    if (typeof doc.applyLogger === 'function') doc.applyLogger()
+    if (logger) doc.getLogger().delegate = logger
+    doc.catalog.syntheticIds = {}
+    doc.source_header_attributes ??= toHash()
+    const isRootPage = isRootEntry
+    const { component, version, module: module_, relative, origin } = page.src
+    const doctypeOverride = doc.getAttribute('assembly-doctype')
+    if (doctypeOverride) {
+      if (doctypeOverride !== doctype) builder.setDoctype(doctypeOverride)
+      if (doctypeOverride !== 'book') atBookRoot = supportsParts = false
+    }
+    if (isRootPage && doc.hasAttribute('assembly-slug')) builder.slug = doc.getAttribute('assembly-slug')
+    let hasAssemblyNavtitleAttr
+    if ((hasAssemblyNavtitleAttr = !!doc.getAttribute('assembly-navtitle'))) {
       navtitleAsciiDoc = doc.getAttribute('assembly-navtitle')
       navtitlePlain = sanitize((navtitle = doc.$apply_reftext_subs(navtitleAsciiDoc)))
-      if (buffer.inBody == null) {
-        buffer.navtitle = navtitle
-        // Q do we need to assert !level here?
-        if (assemblyModel.rootLevel) {
-          let doctitle = navtitleAsciiDoc
-          if (navtitlePlain !== componentVersion.title) doctitle = `${componentVersion.title}: ${doctitle}`
-          buffer[0] = `= ${doctitle}`
-        }
-      }
-    }
-    if (atDocumentRoot) {
-      const authors = doc.getAuthors()
-      if (authors.length) {
-        const authorLine = authors
-          .map((author) => {
-            const email = author.getEmail()
-            return email ? `${author.getName()} <${author.getEmail()}>` : author.getName()
-          })
-          .join('; ')
-        buffer.splice(1, 0, authorLine)
-      }
+      if (isRootPage) builder.setDoctitle(navtitle, navtitleAsciiDoc, navtitlePlain)
     }
+    const overviewTitle = doc.getAttribute('assembly-overview-title', 'Overview')
+    let overviewTitleAsciiDoc
     // 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
-    let pageFragment = ''
-    let pageRoles = ''
+    const pageId = generateScopedId(page.src, componentVersion, idSeparators, filetype)
+    const pageIdLeader = pageId + idSeparators.scope
+    let pageFragment = `#${pageId}`
+    let pageRoles = []
     let pageStyle = doc.getAttribute('assembly-style', '')
+    if (!pageStyle && isRootPage && hasItems && !doc.source_header_attributes['$key?']('assembly-style')) {
+      pageStyle = rootPageStyle
+    }
     let part
-    if ((part = pageStyle === 'part')) {
-      pageStyle = ''
-      if (!supportsParts) part = undefined
-    } else if ((part = pageStyle.endsWith('-part'))) {
-      pageStyle = pageStyle.slice(0, -5)
-      if (!supportsParts) part = undefined
+    if (pageStyle) {
+      if (
+        pageStyle === 'part' ||
+        (pageStyle.endsWith('-part') && (pageStyle = pageStyle.substring(0, pageStyle.length - 5)))
+      ) {
+        part = supportsParts ? true : (pageStyle = undefined)
+      }
+    } else {
+      pageStyle = undefined
     }
-    let nextSectionLevel = 1
+    const hasSections = doc.hasSections()
+    const supportsSections = pageStyle == null ? true : ASSEMBLY_STYLE_SUPPORTS_SECTIONS.includes(pageStyle)
+    const encloseSections = sectionMergeStrategy === 'enclose' && hasItems && hasSections
+    let nextSectionLevel = atBookRoot ? undefined : 1 // undefined means allow part or chapter at top level
     const lines = doc.getSourceLines()
     const ignoreLines = []
-    buffer.inBody = true
-    buffer.push('')
-    buffer.push(`:docname: ${docname}`)
-    if (component !== lastComponentVersion.name) {
+    const buffer = (builder.body ??= [])
+    if (buffer.length) buffer.push('')
+    if (doc.hasHeader()) {
+      for (const entry of processPageHeader(doc, lines, ignoreLines, isRootPage)) {
+        if (entry.type === 'author_line') {
+          builder.setAuthor(entry.lines[0])
+        } else if (entry.type === 'attribute_entry') {
+          const name = entry.name
+          if (entry.negated && name === 'sectnums') {
+            // catch sectnums missed by reducer; only allow turned off, not turning on
+            doc.source_header_attributes['$[]=']('sectnums', null)
+          } else 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)) != null
+            ) {
+              if (newVal !== val) entry.lines = [`:${name}: ${newVal}`]
+            } else if (~(val = entry.lines.join('\n').substring(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')
+            }
+          }
+          ;(entry.promote ? builder.header : buffer).push(...entry.lines)
+        } else {
+          if (entry.type === 'attrlist') builder.headerHasBlockAttrs = true
+          buffer.push(...entry.lines)
+        }
+      }
+      pageRoles = doc.getRoles()
+    }
+    if (roles.length) pageRoles = pageRoles.concat(roles[0] === 'page' ? roles.slice(1) : roles)
+    buffer.push(`:page-docname: ${docname}`)
+    if (component !== builder.currentComponentVersion.name) {
       const thisComponentVersion =
         component === componentVersion.name && version === componentVersion.version
           ? componentVersion
@@ -211,7 +367,7 @@ function mergeAsciiDoc (
         buffer.push(':page-version: {page-component-version}')
         buffer.push(`:page-component-display-version: ${thisComponentVersion.displayVersion}`)
         buffer.push(`:page-component-title: ${thisComponentVersion.title}`)
-        lastComponentVersion = thisComponentVersion
+        builder.currentComponentVersion = thisComponentVersion
       }
     }
     buffer.push(`:page-module: ${module_}`)
@@ -221,90 +377,120 @@ function mergeAsciiDoc (
     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)
     let heading
-    if (pageStyle && (part && level === 1 ? (level = 0) : level) === 0) {
-      let htitleAsciiDoc = navtitleAsciiDoc
-      let htitlePlain = navtitlePlain
-      let htitleOverride
-      if (
-        (htitleOverride = pageStyle === 'preface' ? doc.getAttribute('preface-title') : undefined) ||
-        (atDocumentRoot && (htitleOverride = outlineEntry.navtitle))
-      ) {
+    if (pageStyle != null && isRootPage) {
+      let htitleAsciiDoc, htitleOverride
+      if (pageStyle === 'preface') {
+        const hasPrefaceTitleAttr =
+          doc.isAttribute('preface-title') ||
+          doc.source_header_attributes['$key?']('preface-title') ||
+          doc.isAttributeLocked('preface-title')
+        if (hasPrefaceTitleAttr) {
+          htitleOverride = doc.getAttribute('preface-title', '')
+        } else if (!(htitleOverride = doc.getAttribute('assembly-root-title'))) {
+          if (encloseSections) {
+            htitleOverride = overviewTitle
+          } else if (builder.matchesDoctitle(navtitlePlain)) {
+            htitleOverride = ''
+          } else {
+            htitleOverride = undefined // means use navtitleAsciiDoc
+          }
+        }
+        if (htitleOverride === '') {
+          nextSectionLevel = 2
+          if (builder.headerHasBlockAttrs) {
+            htitleAsciiDoc = ''
+          } else {
+            sectionMergeStrategy = 'discrete'
+            if (atBookRoot && hasPrefaceTitleAttr) {
+              builder.header.push(':preface-title:')
+            }
+          }
+        } else {
+          htitleAsciiDoc = htitleOverride == null ? navtitleAsciiDoc : unconvertInlineAsciiDoc(htitleOverride)
+          if (htitleOverride === overviewTitle) overviewTitleAsciiDoc = htitleAsciiDoc // optimization
+          if (atBookRoot && hasPrefaceTitleAttr) {
+            if (!builder.headerHasBlockAttrs && (sectionMergeStrategy === 'discrete' || !hasSections)) {
+              builder.header.push(`:preface-title: ${htitleAsciiDoc}`)
+              htitleAsciiDoc = undefined
+            }
+          }
+        }
+      } else if ((htitleOverride = doc.getAttribute('assembly-root-title', ''))) {
         htitleAsciiDoc = unconvertInlineAsciiDoc(htitleOverride)
-        htitlePlain = sanitize(htitleOverride)
-      }
-      if (atDocumentRoot && pageStyle === 'preface' && htitlePlain === componentVersion.title) {
-        assemblyModel = Object.assign({}, assemblyModel, { sectionMergeStrategy: 'discrete' })
+      } else if (encloseSections) {
+        htitleAsciiDoc = overviewTitleAsciiDoc = unconvertInlineAsciiDoc(overviewTitle)
       } else {
-        if (atDocumentRoot) {
-          pageFragment = `#${idPrefix}${doc.getId() ?? pageStyle}`
-          buffer.unshift(`[#${idScope}]`)
+        htitleAsciiDoc = navtitleAsciiDoc
+      }
+      if (htitleAsciiDoc != null) {
+        heading = { title: htitleAsciiDoc, hlevel: part ? 1 : 2 }
+        if (pageStyle === 'part') {
+          nextSectionLevel = 1
         } else {
-          pageFragment = `#${idScope}`
+          nextSectionLevel = 2 // next section level is 2, even for special part
+          // enable next two lines if we always want to promote ID of root page to docid
+          //builder.setDocid(pageId)
+          //pageFragment = '#' + idSeparators.generateIdFromTitle(htitleAsciiDoc, idSeparators, pageIdLeader)
+          if (pageStyle === 'preface' && doctype !== 'book') {
+            heading.style = ''
+            if (doc.hasAttribute('sectnums')) {
+              doc.source_header_attributes['$[]=']('sectnums', null)
+              buffer.push(':!sectnums:')
+            }
+          }
         }
-        heading = { title: htitleAsciiDoc, level: part ? 1 : 2 }
-        nextSectionLevel++
       }
+    } else if (part) {
+      heading = { title: navtitleAsciiDoc, hlevel: level-- } // NOTE: level will always come in at 1
+      nextSectionLevel = pageStyle === 'part' ? 1 : 2
     } else if (level) {
-      if (atDocumentRoot && navtitlePlain === componentVersion.title) {
+      if (atStartOfBody && !pageStyle && builder.matchesDoctitle(navtitlePlain)) {
         level--
-      } else {
-        pageFragment = `#${idScope}`
-        if (part && level === 1) level--
-        if ((heading = { title: navtitleAsciiDoc, level: level + 1 }).level > 6) {
-          Object.assign(heading, { level: 6, style: `discrete.h${heading.level}` })
-        }
+      } else if ((heading = { title: navtitleAsciiDoc, hlevel: level + 1 }).hlevel > 6) {
+        Object.assign(heading, { hlevel: 6, style: `discrete.h${heading.hlevel}` })
       }
     }
     if (heading) {
-      buffer.push(`[${heading.style ?? pageStyle}${pageFragment}${pageRoles}]`)
-      buffer.push(`${'='.repeat(heading.level)} ${heading.title}`)
-    } else if (atDocumentRoot) {
-      buffer.unshift(`[#${idScope}]`)
-    }
-    let enclosed
-    if (assemblyModel.sectionMergeStrategy === 'enclose' && hasItems && doc.hasSections()) {
-      enclosed = true
-      // TODO: make overview section title configurable
-      //let overviewTitle = doc.getDocumentTitle()
-      //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 rolesAttr = pageRoles.reduce((str, it) => str + '.' + it, '')
+      const notitle = (heading.title ||= '{empty}') === '{empty}'
+      // remove conditional if we always want to promote ID of root page to docid
+      if (notitle) {
+        builder.setDocid(pageId)
+        pageFragment = '#' + idSeparators.generateIdFromTitle('', idSeparators, pageIdLeader)
       }
-      let hlevel = level + 2
+      const style = heading.style ?? (pageStyle === 'part' || pageStyle === 'section' ? '' : (pageStyle ?? ''))
+      buffer.push(`[${style}${pageFragment}${rolesAttr}${notitle ? '%notitle' : ''}]`)
+      buffer.push(`${'='.repeat(heading.hlevel)} ${heading.title}`)
+      if (notitle || !supportsSections) sectionMergeStrategy = 'discrete'
+    } else if (atStartOfBody) {
+      builder.setDocid(pageId)
+    }
+    if (isRootPage || (atStartOfBody && !heading)) assembled.pages.rootPageFragment = pageFragment
+    assembled.pages.set(page, pageFragment)
+    if (encloseSections && !(atStartOfBody && heading)) {
+      overviewTitleAsciiDoc ??= unconvertInlineAsciiDoc(overviewTitle)
+      const sectionFragment = '#' + idSeparators.generateIdFromTitle(overviewTitleAsciiDoc, idSeparators, pageIdLeader)
+      if (heading && buffer.length) buffer.push('')
+      let hlevel = level + (nextSectionLevel = 2)
       if (hlevel > 6) {
-        const blockStyle = `discrete.h${hlevel}`
+        buffer.push(`[discrete.h${hlevel}${sectionFragment}]`)
         hlevel = 6
-        buffer.push(syntheticId ? `[${blockStyle}#${syntheticId}]` : `[${blockStyle}]`)
-      } else if (syntheticId) {
-        buffer.push(`[#${syntheticId}]`)
+      } else {
+        buffer.push(`[${sectionFragment}]`)
       }
-      buffer.push(`${'='.repeat(hlevel)} ${overviewTitle}`)
-      if (toggleSectids) buffer.push(':sectids:')
-    }
-    pagesInOutline.assembled.pages.set(page, pageFragment)
-    if (doc.hasSections()) {
-      fixSectionLevels(doc.getSections(), atBookRoot && !pageStyle ? undefined : nextSectionLevel)
+      buffer.push(`${'='.repeat(hlevel)} ${overviewTitleAsciiDoc}`)
     }
+    if (hasSections) fixSectionLevels(doc.getSections(), nextSectionLevel)
     const allBlocks = doc.findBy({ traverse_documents: true }, (it) =>
       it.getContext() === 'document'
         ? it.getDocument().isNested()
         : !(it.getContext() === 'table_cell' && it.getStyle() === 'asciidoc')
     )
     if (doc.getDoctype() === 'manpage') {
-      const firstSectionIdx = doc.hasSections() ? doc.getSections()[0].getLineNumber() - 1 : lines.length
+      const firstSectionIdx = hasSections ? doc.getSections()[0].getLineNumber() - 1 : lines.length
       for (let idx = 0; idx < firstSectionIdx; idx++) {
-        if (~ignoreLines.indexOf(idx)) continue
+        if (ignoreLines.includes(idx)) continue
         const line = lines[idx]
         if (line.startsWith('== ') && line.length > 3) {
           allBlocks.unshift({
@@ -348,10 +534,10 @@ function mergeAsciiDoc (
     })
     let skipping
     for (let idx = 0, lastIdx = lines.length - 1; idx <= lastIdx; idx++) {
-      if (~ignoreLines.indexOf(idx)) continue
+      if (ignoreLines.includes(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
@@ -366,7 +552,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
@@ -378,111 +564,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 relativePart, fragment, resource, isPage
-          const hashIdx = target.indexOf('#')
-          const dollarIdx = target.indexOf('$')
-          if (~hashIdx) {
-            relativePart = target.slice(0, hashIdx)
-            fragment = target.slice(hashIdx + 1)
-          } else if (~dollarIdx || target.endsWith('.adoc')) {
-            relativePart = target
-            fragment = ''
-          } else {
-            fragment = target
-          }
-          // Q: should we validate the internal ID here?
-          if (!relativePart) return `xref:${idPrefix}${fragment}[${text}]`
-          if (~dollarIdx) {
-            if (relativePart.slice(dollarIdx).startsWith('$./')) {
-              relativePart = relativePart.slice(0, dollarIdx + 1) + topicPrefix + relativePart.slice(dollarIdx + 3)
-            }
-            if ((isPage = /\bpage\$/.test(relativePart))) relativePart = relativePart.replace('page$', '')
-          } else {
-            isPage = true
-            if (relativePart.startsWith('./')) relativePart = topicPrefix + relativePart.slice(2)
-            if (~hashIdx && !relativePart.endsWith('.adoc')) relativePart += '.adoc'
-          }
-          if (!isPage || ~relativePart.indexOf('@') || /:.*:/.test(relativePart)) {
-            if (siteRoot && (resource = contentCatalog.resolveResource(relativePart, page.src, 'page'))?.pub) {
-              text ||= resource.asciidoc?.xreftext || target
-              return `${resolveLinkTarget(resource, siteRoot, pubRoot, linkRefStyle)}${fragment && '#' + fragment}[${text}]`
-            }
-            // TODO: handle unresolved resource better
-            return m
-          }
-          let targetModule
-          const colonIdx = relativePart.indexOf(':')
-          if (~colonIdx) {
-            targetModule = relativePart.slice(0, colonIdx)
-            relativePart = relativePart.slice(colonIdx + 1)
-            if (relativePart.startsWith('./')) relativePart = topicPrefix + relativePart.slice(2)
-          } else {
-            targetModule = module_
-          }
-          const pageResourceRef = targetModule === 'ROOT' ? relativePart : `${targetModule}:${relativePart}`
-          if (!(resource = pagesInOutline.get(pageResourceRef))) {
-            if (siteRoot && (resource = contentCatalog.resolvePage(pageResourceRef, page.src)) && resource.out) {
-              text ||= resource.asciidoc?.xreftext || target
-              return `${resolveLinkTarget(resource, siteRoot, pubRoot, linkRefStyle)}${fragment && '#' + fragment}[${text}]`
-            }
-            // TODO: handle unresolved page better
-            return m
-          }
-          if (targetModule !== 'ROOT') relativePart = `${targetModule}${idCoordinateSeparator}${relativePart}`
-          relativePart = relativePart.replace(/\.adoc$/, '').replace(/[/.]/g, '-')
-          if (fragment === resource.asciidoc.id) fragment = ''
-          const refid = fragment
-            ? `${relativePart}${idScopeSeparator}${fragment}`
-            : relativePart + (ReservedIdNames.includes(relativePart) ? idScopeSeparator : '')
-          if (
-            text &&
-            (assemblyModel.dropExplicitXrefText === 'always' ||
-              (assemblyModel.dropExplicitXrefText === 'if-redundant' && text === resource.title))
-          ) {
-            text = ''
-          }
-          return `xref:${refid}[${text}]`
+        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 =
-            siteRoot &&
-            contentCatalog.getById({
-              component: componentVersion.name,
-              version: componentVersion.version,
-              module: module_,
-              family: 'attachment',
-              relative,
-            })
-          // TODO: handle unresolved attachment page
-          return attachment?.out ? `${resolveLinkTarget(attachment, siteRoot, pubRoot, linkRefStyle)}[${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 && (filetype !== 'html' || siteRoot)) {
-              pagesInOutline.assembled.assets.add(image)
-              return filetype === 'html'
-                ? `image:${resolveLinkTarget(image, siteRoot, pubRoot, linkRefStyle)}[${attrlist}]`
-                : `image:${resolveEmbedTarget(image, outDirname, embedRefStyle, true)}[${attrlist}]`
-            }
-          }
-          return m
-        })
+        line = rewriteInlineImages(line, contentCatalog, assemblyModel, page.src, assembled.assets, true, doc)
       }
       lines[idx] = line
     }
@@ -498,9 +604,9 @@ function mergeAsciiDoc (
       let idx = lineno - 1
       if (context === 'section' && !block.getDocument().isNested()) {
         if (block.getSectionName() === 'header') return
-        let blockStyle = (assemblyModel.sectionMergeStrategy || 'discrete') === 'discrete' ? 'discrete' : undefined
+        let blockStyle = sectionMergeStrategy === 'discrete' ? 'discrete' : undefined
         lines[idx] = lines[idx].replace(/^=+ (.+)/, (_, rest) => {
-          let targetMarkerLength = block.level + 1 + level + (enclosed ? 1 : 0)
+          let targetMarkerLength = block.level + 1 + level
           if (targetMarkerLength > 6) {
             blockStyle = `discrete.h${targetMarkerLength}`
             targetMarkerLength = 6
@@ -508,56 +614,49 @@ 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] || ''
           let prefix = ''
           // Q: can we use startsWith('image::') in certain cases?
           let imageMacroOffset = (
-            lastImageMacroAt?.[0] === idx ? line.slice(0, lastImageMacroAt[1]) : line
+            lastImageMacroAt?.[0] === idx ? line.substring(0, lastImageMacroAt[1]) : line
           ).lastIndexOf('image::')
           if (imageMacroOffset > 0) {
             if (
               block.getDocument().isNested() &&
-              (prefix = line.slice(0, imageMacroOffset)).trimRight().endsWith('|')
+              (prefix = line.substring(0, imageMacroOffset)).trimRight().endsWith('|')
             ) {
-              line = line.slice(prefix.length)
+              line = line.substring(prefix.length)
             } else {
               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 && (filetype !== 'html' || siteRoot)) {
-                const attrlist = line.slice(line.indexOf('[') + 1, -1)
-                pagesInOutline.assembled.assets.add(image)
-                lines[idx] =
-                  filetype === 'html'
-                    ? `${prefix}image::${resolveLinkTarget(image, siteRoot, pubRoot, linkRefStyle, false)}[${attrlist}]`
-                    : `${prefix}image::${resolveEmbedTarget(image, outDirname, embedRefStyle)}[${attrlist}]`
-              }
-            }
+            const newTarget = rewriteImageRef(target, contentCatalog, assemblyModel, page.src, assembled.assets)
+            if (newTarget) lines[idx] = `${prefix}image::${newTarget}${line.substring(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 = doc.source_header_attributes.$entries()
     if (attributeEntries.length) {
       const resolvedAttributeEntries = attributeEntries.reduce(
         (accum, [name, val]) => {
+          if (val) {
+            if (val['$nil?']()) val = null
+          }
           // Q: couldn't we just check if attribute is locked?
           if (name in mutableAttributes) {
             const initialVal = mutableAttributes[name]
@@ -566,7 +665,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
@@ -575,87 +674,88 @@ function mergeAsciiDoc (
       )
       if (resolvedAttributeEntries.length > 1) safePush(buffer, resolvedAttributeEntries)
     }
-  } else if (level) {
-    if (atDocumentRoot && navtitlePlain === componentVersion.title) {
-      buffer.inBody ??= false
+    if (typeof doc.restoreLogger === 'function') doc.restoreLogger()
+  } else if (level && !hash) {
+    const buffer = (builder.body ??= [])
+    if (atStartOfBody && builder.matchesDoctitle(navtitlePlain)) {
       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()}`
-        }
-      }
+      if (buffer.length) buffer.push('')
+      const syntheticId = idSeparators.generateIdFromTitle(navtitleAsciiDoc, idSeparators)
       let sectionTitle = navtitleAsciiDoc
       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)) {
-            let refid = resource.src.relative.replace(/\.adoc$/, '').replace(/[/.]/g, '-')
-            if (refid.startsWith('./')) refid = topicPrefix + refid.slice(2)
-            if (resource.src.module !== 'ROOT') refid = `${resource.src.module}${idCoordinateSeparator}${refid}`
+            const refid = generateScopedId(resource.src, componentVersion, idSeparators, filetype, true)
             sectionTitle = `xref:${refid}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
           } else if (siteRoot) {
-            sectionTitle = `${resolveLinkTarget(resource, siteRoot, pubRoot, linkRefStyle)}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+            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(`[#${syntheticId}]`)
+      if (supportsParts && level === 1 && roles.includes('part')) {
+        roles.splice(roles.indexOf('part', 1))
+        level--
       }
+      const hlevel = level > 5 ? 6 : level + 1
+      const hroles = urlType === 'internal' ? roles.slice(1) : roles
+      buffer.push(`[${hlevel > 6 ? 'discrete' : ''}#${syntheticId}${hroles.reduce((str, it) => str + '.' + it, '')}]`)
       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?
-    ;(urlType === 'internal' && urlType === items[0].urlType && url === items[0].url && !items[0].items
-      ? items.slice(1)
-      : items
-    ).forEach((item) => {
-      mergeAsciiDoc(
-        loadAsciiDoc,
-        contentCatalog,
-        buffer,
-        componentVersion,
-        item,
-        files,
-        pagesInOutline,
-        asciidocConfig,
-        mutableAttributes,
-        assemblyModel,
-        lastComponentVersion,
-        nextLevel,
-        atBookRoot
-      )
-    })
-  }
-  return buffer
+  if (!hasItems) return
+  const nextLevel = level + 1
+  // NOTE: drop first child if same as parent; should we keep if content is different?
+  ;(urlType === 'internal' && items[0].urlType === 'internal' && pathname === items[0].url && !items[0].items?.length
+    ? items.slice(1)
+    : items
+  ).forEach((item) => {
+    mergeAsciiDoc(
+      loadAsciiDoc,
+      contentCatalog,
+      builder,
+      componentVersion,
+      item,
+      files,
+      pagesInOutline,
+      idSeparators,
+      asciidocConfig,
+      mutableAttributes,
+      assemblyModel,
+      nextLevel,
+      atBookRoot
+    )
+  })
 }
 
-function processDocumentHeader (doc, lines, buffer, ignoreLines) {
+function processPageHeader (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')
+    }
+    for (const name of assemblyHeaderAttributes) doc.source_header_attributes.$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) {
@@ -666,41 +766,54 @@ 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.appendLine(line)
+      if (!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.appendLine(line)
+            if (open === line) current = open = undefined
+          } else {
+            entries.push((current = { type: 'block_comment', lines: [(open = line)] }))
+            current.appendLine = Array.prototype.push.bind(current.lines)
+          }
+        } else if (open) {
+          current.appendLine(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.appendLine(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) && !assemblyHeaderAttributes.has(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: [], lineno: idx + 1 }))
+          current.lines.push(negated ? `:!${name}:` : line)
+          current.appendLine = Array.prototype.push.bind(negated ? [] : current.lines)
+          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)
+          .substring(1, line.length - 1)
           .trim()
-          .replace(/(?:^\w[\w-]*(?!=|[\w-]))?([#.%]\w[\w-]*)*/, '')
-        if (attrlist) buffer.push('[' + attrlist + ']')
+          .replace(/(?:^\w[\w-]*(?!=|[\w-]))?([#.]\w[\w-]*)*/, '')
+          .replace(NAMED_ID_ATTR_RX, '')
+        if (attrlist) entries.push({ type: 'attrlist', lines: ['[' + attrlist + ']'] })
       }
     } else if (belowDoctitle) {
       break
@@ -708,23 +821,26 @@ 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
-    .toLowerCase()
-    .replace(/<[^>]+>/g, '')
-    .replace(CharRefRx, (_, name, dec, hex) => {
-      if (name) return BuiltInNamedEntities[name] ?? '?'
-      return String.fromCharCode(dec ? parseInt(dec, 10) : parseInt(hex, 16))
-    })
-    .replace(/[\x27\u2019]/g, '')
-    .replace(/[^\p{Alpha}0-9-]/gu, '-')
-    .replace(/^-+|-+$|(-)-+/g, '$1')
+function generateSlug (string) {
+  if (string === 'index') return string
+  return sanitizeSlug(
+    string
+      .toLowerCase()
+      .replace(/<[^>]+>/g, '')
+      .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(/[_.]/, '-')
+  )
+}
+
+function sanitizeSlug (slug) {
+  return slug.replace(/[^\p{Alpha}0-9_.-]/gu, '-').replace(/^-+|-+$|(-)-+/g, '$1')
 }
 
 function fixSectionLevels (sections, expectedLevel) {
@@ -735,115 +851,29 @@ 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.id(obj)
-}
-
-// NOTE: blank lines at top and bottom of document create mismatch when using line numbers to navigate source lines
-// IMPORTANT: this must not leave behind lines the parser will drop!
-// IDEA: another option is to capture initial lineno of reader and use as offset (but preseves those blank lines)
-function trimAsciiDoc (buffer) {
-  return Buffer.from(
-    buffer
-      .toString()
-      .replace(/^(?:[ \t]*\r\n?|[ \t]*\n)+/, '')
-      .trimRight()
-  )
-}
-
 function safePush (onto, entries) {
   try {
     onto.push(...entries)
-  } catch (err) {
-    /* istanbul ignore if */
-    if (!(err instanceof RangeError)) throw err
+  } catch {
     for (const e of entries) onto.push(e)
   }
 }
 
-function resolveEmbedTarget (resource, outDirname, referenceStyle, escapeForInline) {
-  const target =
-    referenceStyle === 'output-relative' ? resource.out.path : path.relative(outDirname + '/', resource.out.path)
-  return escapeForInline ? target.replace(/_/g, '{underscore}') : target
-}
-
-function resolveLinkTarget (resource, siteRoot, pubRoot, referenceStyle, escapeForInline = true) {
-  let target
-  if (resource.site?.url) {
-    target = ['', resource.pub.url]
-  } else {
-    switch (referenceStyle) {
-      case 'absolute':
-        target = ['', siteRoot.url + resource.pub.url]
-        break
-      case 'root-relative':
-        target = ['link:', siteRoot.path + resource.pub.url]
-        break
-      default:
-        target = ['link:', computeRelativeUrl(pubRoot + '/', resource.pub.url)]
-    }
+function generateIdFromTitle (titleAsciiDoc, idSeparators, idLeader) {
+  const Section = this.$class().$$base_module.Section
+  // NOTE: refs in catalog will always be empty
+  const baseId = titleAsciiDoc ? Section.$generate_id(titleAsciiDoc, this) : '_'
+  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().$$base_module.Compliance.unique_id_start_index
+    let candidate
+    while ((candidate = `${id}${sep}${cnt}`) in syntheticIds) cnt++
+    id = candidate
   }
-  if (escapeForInline) target[1] = target[1].replace(/_/g, '{underscore}')
-  return target.join('')
-}
-
-function computeRelativeUrl (from, to) {
-  const rel = path.relative(from, to)
-  return to.charAt(to.length - 1) === '/' ? rel + '/' : rel
+  syntheticIds[id] = true
+  return id
 }
 
 module.exports = produceAssemblyFile