@antora/assembler 1.0.0-rc.1 → 1.0.0-rc.11

package/lib/produce-assembly-file.js

@@ -11,22 +11,29 @@ const {
   rewriteStyleAttribute,
 } = require('./util/rewriter')
 const sanitize = require('./util/sanitize')
+const toHash = require('./util/to-hash')
 const unconvertInlineAsciiDoc = require('./util/unconvert-inline-asciidoc')
 
 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',
-  'preface-title',
+  'assembly-docname',
+  'assembly-doctitle',
+  'assembly-doctype',
   'assembly-header-attributes',
+  'assembly-overview-title',
   'assembly-navtitle',
-  'assembly-slug',
+  'assembly-root-title',
   '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,
@@ -39,35 +46,39 @@ function produceAssemblyFile (
   assemblyModel
 ) {
   const pagesByUrl = files.reduce((map, it) => (it.src.family === 'page' ? map.set(it.pub.url, it) : map), new Map())
-  if (outline.urlType === 'internal' && !pagesByUrl.get(outline.url) && !(outline.items || []).length) return
   const pagesInOutline = selectPagesInOutline(outline, pagesByUrl)
+  if (outline.urlType === 'internal' && !pagesByUrl.has(outline.pathname) && !outline.items?.length) return
+  const { 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(
-      loadAsciiDoc(
-        { contents: Buffer.alloc(0), src: { family: 'page', relative: 'generate-id-from-title.adoc' } },
-        undefined,
-        asciidocConfig
-      )
-    ),
+    generateIdFromTitle: generateIdFromTitle.bind(scratchDoc),
   }
-  const { name: component, version } = componentVersion
   asciidocConfig = prepareAsciiDocConfig(
     contentCatalog,
     { component, version },
     pagesInOutline,
     asciidocConfig,
     assemblyModel,
-    idSeparators
+    idSeparators,
+    scratchDoc
   )
-  const buffer = mergeAsciiDoc(
+  const builder = buildAssemblyHeader(componentVersion, outline.content, assemblyModel)
+  mergeAsciiDoc(
     loadAsciiDoc,
     contentCatalog,
-    buildAsciiDocHeader(componentVersion, outline.content, assemblyModel),
+    builder,
     componentVersion,
     outline,
     files,
@@ -78,22 +89,24 @@ function produceAssemblyFile (
     assemblyModel
   )
   const stem =
-    (buffer.slug ? sanitizeSlug(buffer.slug) : generateSlug(rootLevel === 0 ? 'index' : buffer.navtitle)) ||
+    (builder.docname
+      ? sanitizeDocname(builder.docname)
+      : generateDocname(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'),
+    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 file path so assets can easily be published to same hierarchy
+  file.path = file.out.path // use out path as path so assets can be published to same hierarchy
   delete file.out
   return file
 }
 
-function prepareAsciiDocConfig (contentCatalog, ctx, pagesInOutline, asciidocConfig, assemblyModel, idSeparators) {
+function prepareAsciiDocConfig (contentCatalog, ctx, pagesInOutline, asciidocConfig, assemblyModel, idSeparators, doc) {
   let attributesModified
   const configShared = asciidocConfig.$shared
   const sharedAttributes = asciidocConfig.attributes
@@ -101,7 +114,7 @@ function prepareAsciiDocConfig (contentCatalog, ctx, pagesInOutline, asciidocCon
     if (configShared == null) {
       const assets = pagesInOutline.assembled.assets
       for (const [name, val] of Object.entries(sharedAttributes)) {
-        if (!(typeof val === 'string' && ~val.indexOf(':'))) continue
+        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:')) {
@@ -112,9 +125,19 @@ function prepareAsciiDocConfig (contentCatalog, ctx, pagesInOutline, asciidocCon
       }
     }
     for (const [name, val] of Object.entries(sharedAttributes)) {
-      if (!(typeof val === 'string' && ~val.indexOf(':'))) continue
+      if (!(val?.constructor === String && ~val.indexOf(':'))) continue
       if (~val.indexOf('xref:')) {
-        const newVal = rewriteXrefs(val, contentCatalog, assemblyModel, ctx, false, pagesInOutline, idSeparators)
+        const newVal = rewriteXrefs(
+          val,
+          contentCatalog,
+          assemblyModel,
+          ctx,
+          false,
+          pagesInOutline,
+          idSeparators,
+          null,
+          doc
+        )
         if (newVal !== val) (attributesModified ??= {})[name] = newVal
       }
     }
@@ -123,43 +146,74 @@ function prepareAsciiDocConfig (contentCatalog, ctx, pagesInOutline, asciidocCon
   return Object.assign({}, asciidocConfig, { attributes: Object.assign({}, sharedAttributes, attributesModified) })
 }
 
-function buildAsciiDocHeader (componentVersion, navtitle, assemblyModel) {
-  const doctype = assemblyModel.doctype ?? 'book'
-  const navtitlePlain = sanitize(navtitle)
+function buildAssemblyHeader (componentVersion, navtitle, assemblyModel) {
+  const { name: componentName, version, displayVersion, title } = componentVersion
   const navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
-  const doctitle = (componentVersion.title === navtitlePlain ? '' : componentVersion.title + ': ') + navtitleAsciiDoc
-  const version = componentVersion.version === 'master' ? '' : componentVersion.version
-  const displayVersion = componentVersion.displayVersion
-  const buffer = [
-    `= ${doctitle}`,
-    ...(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: ${displayVersion}`,
-    `:page-component-title: ${componentVersion.title}`,
-  ]
-  return Object.assign(buffer, { navtitle })
+  const navtitlePlain = sanitize(navtitle)
+  const doctitleQualifier = assemblyModel.rootLevel === 0 ? undefined : 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)
+    },
+    updateDoctitle (doctitle, doctitleAsciiDoc, doctitlePlain, useQualifier = true) {
+      this.baseDoctitle = doctitle
+      this.baseDoctitlePlain = doctitlePlain
+      const qualifyDoctitle = useQualifier && !!this.doctitleQualifier && this.doctitleQualifier !== doctitlePlain
+      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, accum) {
   accum ??= Object.assign(new Map(), { assembled: { pages: new Map(), assets: new Set() } })
-  const page = outlineEntry.urlType === 'internal' ? pagesByUrl.get(outlineEntry.url) : undefined
-  if (page) {
-    accum.set(createResourceKey(page.src), page)
-    accum.set(outlineEntry.url, page)
+  const { urlType, url, hash, unresolved, items = [] } = outlineEntry
+  if (urlType === 'internal' && !unresolved) {
+    const pathname = (outlineEntry.pathname ??= hash ? url.substring(0, url.length - hash.length) : url)
+    let page
+    if (!accum.has(pathname) && (page = pagesByUrl.get(pathname))) {
+      accum.set(createResourceKey(page.src), page)
+      accum.set(pathname, page)
+    }
   }
-  for (const item of outlineEntry.items || []) selectPagesInOutline(item, pagesByUrl, accum)
+  for (const item of items) selectPagesInOutline(item, pagesByUrl, accum)
   return accum
 }
 
 function mergeAsciiDoc (
   loadAsciiDoc,
   contentCatalog,
-  buffer,
+  builder,
   componentVersion,
   outlineEntry,
   files,
@@ -168,133 +222,115 @@ function mergeAsciiDoc (
   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.navtitle ?? outlineEntry.content
-  let navtitlePlain = sanitize(navtitle)
-  let navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
-  const { items = [], roles = [], unresolved, urlType, url } = outlineEntry
-  const { filetype, linkReferenceStyle, pubRoot, siteRoot, logger, rootLevel } = assemblyModel
   const assembled = pagesInOutline.assembled
   // FIXME: ideally, resource ID would be stored in navigation so we can look up the page more efficiently
-  const page = urlType === 'internal' && !unresolved ? pagesInOutline.get(url) : undefined
-  const atDocumentRoot = !buffer.inBody
-  const atBookRoot = atDocumentRoot && !level && assemblyModel.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, rootLevel, 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
   if (page && !assembled.pages.has(page)) {
     const contents = page.src.contents
     if (contents == null) {
-      buffer.inBody ??= false
-      return buffer
+      builder.body ??= []
+      return builder
     }
-    const isRootPage = atDocumentRoot && !level
-    const { component, version, module: module_, relative, origin, mediaType } = page.src
     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)
-    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 (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
     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
-        if (rootLevel) {
-          const doctitle =
-            (componentVersion.title === navtitlePlain ? '' : componentVersion.title + ': ') + navtitleAsciiDoc
-          buffer[0] = `= ${doctitle}`
-        }
+      navtitleAsciiDoc = unconvertInlineAsciiDoc(doc.getAttribute('assembly-navtitle'))
+      navtitlePlain = sanitize((navtitle = doc.$sub_attributes(doc.$apply_reftext_subs(navtitleAsciiDoc))))
+    }
+    if (isRootPage) {
+      const doctypeOverride = doc.getAttribute('assembly-doctype')
+      if (doctypeOverride && doctypeOverride !== doctype) {
+        builder.setDoctype(doctypeOverride)
+        if (doctypeOverride !== 'book') atBookRoot = supportsParts = false
+      }
+      if (doc.hasAttribute('assembly-docname')) builder.docname = doc.getAttribute('assembly-docname')
+      const doctitleOverride = doc.getAttribute('assembly-doctitle')
+      if (doctitleOverride) {
+        let doctitle
+        const doctitleAsciiDoc = unconvertInlineAsciiDoc(doctitleOverride)
+        const doctitlePlain = sanitize((doctitle = doc.$sub_attributes(doc.$apply_reftext_subs(doctitleAsciiDoc))))
+        builder.updateDoctitle(doctitle, doctitleAsciiDoc, doctitlePlain, false)
+      } else if (hasAssemblyNavtitleAttr && rootLevel) {
+        builder.updateDoctitle(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 pageDocname = doc.getAttribute('docname')
     const pageId = generateScopedId(page.src, componentVersion, idSeparators, filetype)
     const pageIdLeader = pageId + idSeparators.scope
-    let pageFragment = ''
+    let pageFragment = `#${pageId}`
     let pageRoles = []
     let pageStyle = doc.getAttribute('assembly-style', '')
-    if (
-      !pageStyle &&
-      atBookRoot &&
-      rootLevel === 0 &&
-      assemblyModel.sectionMergeStrategy === 'fuse' &&
-      !doc.source_header_attributes['$key?']('assembly-style')
-    ) {
-      pageStyle = 'preface'
+    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.substring(0, pageStyle.length - 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 = []
-    if (!buffer.inBody) {
-      buffer.inBody = true
-      buffer.endHeaderIdx = buffer.length - 1
-    }
-    buffer.push('')
-    buffer.push(`:docname: ${docname}`)
-    if (component !== lastComponentVersion.name) {
-      const thisComponentVersion =
-        component === componentVersion.name && version === componentVersion.version
-          ? componentVersion
-          : contentCatalog.getComponentVersion(component, version)
-      if (thisComponentVersion) {
-        buffer.push(`:page-component-name: ${thisComponentVersion.name}`)
-        buffer.push(`:page-component-version:${thisComponentVersion.version ? ' ' + thisComponentVersion.version : ''}`)
-        buffer.push(':page-version: {page-component-version}')
-        buffer.push(`:page-component-display-version: ${thisComponentVersion.displayVersion}`)
-        buffer.push(`:page-component-title: ${thisComponentVersion.title}`)
-        lastComponentVersion = thisComponentVersion
-      }
-    }
-    buffer.push(`:page-module: ${module_}`)
-    buffer.push(`:page-relative-src-path: ${relative}`)
-    buffer.push(`:page-origin-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}`)
+    const buffer = (builder.body ??= [])
+    if (buffer.length) buffer.push('')
     let headerHasBlockAttrs
     if (doc.hasHeader()) {
-      for (const entry of processDocumentHeader(doc, lines, ignoreLines, isRootPage)) {
+      for (const entry of processPageHeader(doc, lines, ignoreLines, isRootPage)) {
         if (entry.type === 'author_line') {
-          buffer.splice(1, 0, entry.lines[0])
-          buffer.endHeaderIdx += 1
+          builder.setAuthor(entry.lines[0])
         } else if (entry.type === 'attribute_entry') {
           const name = entry.name
-          if (!entry.negated && !doc.isAttributeLocked(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))
+              (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(':')) {
+              if (newVal !== val) entry.value = newVal
+            } else if (~(val = entry.value).indexOf(':')) {
               newVal = val
               if (~newVal.indexOf('image:')) {
                 newVal = rewriteInlineImages(
@@ -321,15 +357,10 @@ function mergeAsciiDoc (
                   { file: relative, lineno: entry.lineno }
                 )
               }
-              if (newVal !== val) entry.lines = `:${entry.name}: ${newVal}`.split('\n')
+              if (newVal !== val) entry.value = newVal
             }
           }
-          if (entry.promote) {
-            buffer.splice(buffer.endHeaderIdx + 1, 0, ...entry.lines)
-            buffer.endHeaderIdx += entry.lines.length
-          } else {
-            buffer.push(...entry.lines)
-          }
+          ;(entry.promote ? builder.header : buffer).push(...entry.lines)
         } else {
           if (entry.type === 'attrlist') headerHasBlockAttrs = true
           buffer.push(...entry.lines)
@@ -338,102 +369,144 @@ function mergeAsciiDoc (
       pageRoles = doc.getRoles()
     }
     if (roles.length) pageRoles = pageRoles.concat(roles[0] === 'page' ? roles.slice(1) : roles)
+    buffer.push(`:page-docname: ${pageDocname}`)
+    if (component !== builder.currentComponentVersion.name) {
+      const thisComponentVersion =
+        component === componentVersion.name && version === componentVersion.version
+          ? componentVersion
+          : contentCatalog.getComponentVersion(component, version)
+      if (thisComponentVersion) {
+        buffer.push(`:page-component-name: ${thisComponentVersion.name}`)
+        buffer.push(`:page-component-version:${thisComponentVersion.version ? ' ' + thisComponentVersion.version : ''}`)
+        buffer.push(':page-version: {page-component-version}')
+        buffer.push(`:page-component-display-version: ${thisComponentVersion.displayVersion}`)
+        buffer.push(`:page-component-title: ${thisComponentVersion.title}`)
+        builder.currentComponentVersion = thisComponentVersion
+      }
+    }
+    buffer.push(`:page-module: ${module_}`)
+    buffer.push(`:page-relative-src-path: ${relative}`)
+    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}`)
     let heading
-    if (pageStyle && (part && level === 1 ? (level = 0) : level) === 0) {
-      let htitleAsciiDoc = navtitleAsciiDoc
-      let notitle
+    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')
-        const htitleOverride = hasPrefaceTitleAttr
-          ? doc.getAttribute('preface-title', '')
-          : atDocumentRoot && (rootLevel ? true : !hasAssemblyNavtitleAttr)
-            ? ''
-            : undefined
-        if (htitleOverride != null) {
-          if (htitleOverride === '') {
-            if (headerHasBlockAttrs || doc.hasSections()) {
-              htitleAsciiDoc = '{empty}'
-              notitle = true
-            } else {
-              if (hasPrefaceTitleAttr) buffer.splice(++buffer.endHeaderIdx, 0, ':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 (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 (!headerHasBlockAttrs && (sectionMergeStrategy === 'discrete' || !hasSections)) {
+              builder.header.push(`:preface-title: ${htitleAsciiDoc}`)
               htitleAsciiDoc = undefined
             }
-          } else if (hasPrefaceTitleAttr && !(headerHasBlockAttrs || doc.hasSections())) {
-            buffer.splice(++buffer.endHeaderIdx, 0, `:preface-title: ${unconvertInlineAsciiDoc(htitleOverride)}`)
-            htitleAsciiDoc = undefined
-          } else {
-            htitleAsciiDoc = unconvertInlineAsciiDoc(htitleOverride)
           }
         }
+      } else if ((htitleOverride = doc.getAttribute('assembly-root-title', ''))) {
+        htitleAsciiDoc = unconvertInlineAsciiDoc(htitleOverride)
+      } else if (encloseSections) {
+        htitleAsciiDoc = overviewTitleAsciiDoc = unconvertInlineAsciiDoc(overviewTitle)
+      } else {
+        htitleAsciiDoc = navtitleAsciiDoc
       }
       if (htitleAsciiDoc != null) {
-        if (atDocumentRoot) {
-          // NOTE use pageStyle as fallback because this section must have a unique ID
-          pageFragment = `#${pageIdLeader}${doc.getId() ?? pageStyle}`
-          buffer.unshift(`[#${pageId}]`)
+        heading = { title: htitleAsciiDoc, hlevel: part ? 1 : 2 }
+        if (pageStyle === 'part') {
+          nextSectionLevel = 1
         } else {
-          pageFragment = `#${pageId}`
+          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 }
-        if (notitle) heading.notitle = true
-        nextSectionLevel = 2 // next section level is 2, even for special part
       }
+    } 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 && rootLevel === 0 && navtitlePlain === componentVersion.title && !hasAssemblyNavtitleAttr) {
+      if (atStartOfBody && !pageStyle && builder.matchesDoctitle(navtitlePlain)) {
         level--
+        if (headerHasBlockAttrs) heading = { title: '', hlevel: ++level + 1 }
       } else {
-        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}` })
-        }
+        heading = { title: navtitleAsciiDoc, hlevel: level + 1 }
       }
-    } else if (atDocumentRoot && rootLevel === 0 && hasAssemblyNavtitleAttr) {
-      pageFragment = `#${pageId}`
-      heading = { title: navtitleAsciiDoc, level: (nextSectionLevel = part ? 1 : 2) }
-    } else if (atBookRoot) {
-      nextSectionLevel = undefined
     }
-    let enclosed
     if (heading) {
+      if (heading.hlevel > 6) Object.assign(heading, { hlevel: 6, style: `discrete.h${heading.hlevel}` })
       const rolesAttr = pageRoles.reduce((str, it) => str + '.' + it, '')
-      const notitleAttrs = heading.notitle ? '%notitle,toclevels=0,outlinelevels=0' : ''
-      buffer.push(`[${heading.style ?? pageStyle}${pageFragment}${rolesAttr}${notitleAttrs}]`)
-      buffer.push(`${'='.repeat(heading.level)} ${heading.title}`)
-    } else {
-      if (atDocumentRoot) buffer.unshift(`[#${pageId}]`)
-      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')
-        const syntheticId = idSeparators.generateIdFromTitle(navtitleAsciiDoc, idSeparators)
-        let hlevel = level + 2
-        if (hlevel > 6) {
-          const blockStyle = `discrete.h${hlevel}`
-          hlevel = 6
-          buffer.push(`[${blockStyle}#${syntheticId}]`)
-        } else {
-          buffer.push(`[#${syntheticId}]`)
-        }
-        buffer.push(`${'='.repeat(hlevel)} ${overviewTitle}`)
+      const notitle = (heading.title ||= '{empty}') === '{empty}'
+      // remove conditional if we always want to promote ID of root page to docid
+      if (notitle && atStartOfBody) {
+        builder.setDocid(pageId)
+        pageFragment = '#' + idSeparators.generateIdFromTitle('', idSeparators, pageIdLeader)
       }
+      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 (doc.hasSections()) fixSectionLevels(doc.getSections(), nextSectionLevel)
+    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) {
+        buffer.push(`[discrete.h${hlevel}${sectionFragment}]`)
+        hlevel = 6
+      } else {
+        buffer.push(`[${sectionFragment}]`)
+      }
+      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({
@@ -477,10 +550,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
@@ -547,9 +620,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
@@ -593,10 +666,13 @@ function mergeAsciiDoc (
       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]
@@ -614,19 +690,19 @@ function mergeAsciiDoc (
       )
       if (resolvedAttributeEntries.length > 1) safePush(buffer, resolvedAttributeEntries)
     }
-  } else if (level) {
-    if (atDocumentRoot && rootLevel === 0 && 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('')
+      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)) {
             const refid = generateScopedId(resource.src, componentVersion, idSeparators, filetype, true)
@@ -636,41 +712,42 @@ function mergeAsciiDoc (
           }
         }
       }
+      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 (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,
-        idSeparators,
-        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, ignoreLines, isRootPage) {
+function processPageHeader (doc, lines, ignoreLines, isRootPage) {
   const entries = []
   let assemblyHeaderAttributes = isRootPage && doc.getAttribute('assembly-header-attributes', '%authors')
   assemblyHeaderAttributes = new Set(assemblyHeaderAttributes ? assemblyHeaderAttributes.split(/, */) : undefined)
@@ -690,8 +767,7 @@ function processDocumentHeader (doc, lines, ignoreLines, isRootPage) {
       }
       assemblyHeaderAttributes.delete('%authors')
     }
-    const headerAttributes = doc.source_header_attributes
-    for (const name of assemblyHeaderAttributes) headerAttributes.$delete(name)
+    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
@@ -706,7 +782,7 @@ function processDocumentHeader (doc, lines, ignoreLines, isRootPage) {
     }
     const line = lines[idx]
     if (open === ':' || open === '-:') {
-      if (open === ':') current.lines.push(line)
+      if (open === ':') current.appendLine(line)
       if (!line?.endsWith(' \\')) current = open = undefined
     } else if (line) {
       let attributeEntryMatch
@@ -714,13 +790,14 @@ function processDocumentHeader (doc, lines, ignoreLines, isRootPage) {
       if (chr0 === '/' && line.charAt(1) === '/') {
         if (line.startsWith('////') && line === '/'.repeat(line.length)) {
           if (open) {
-            current.lines.push(line)
+            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.lines.push(line)
+          current.appendLine(line)
         } else if (belowDoctitle && line.charAt(2) === '/') {
           break
         } else {
@@ -728,7 +805,7 @@ function processDocumentHeader (doc, lines, ignoreLines, isRootPage) {
           current = undefined
         }
       } else if (open) {
-        current.lines.push(line)
+        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) === '!'
@@ -737,7 +814,17 @@ function processDocumentHeader (doc, lines, ignoreLines, isRootPage) {
           if (line.endsWith(' \\')) open = '-:' // disallow value continuation
         } else {
           if (line.endsWith(' \\')) open = ':'
-          entries.push((current = { type: 'attribute_entry', name, negated, lines: [line], lineno: idx + 1 }))
+          entries.push((current = { type: 'attribute_entry', name, negated, lines: [], lineno: idx + 1 }))
+          Object.defineProperty(current, 'value', {
+            get () {
+              return this.lines.join('\n').substring(this.name.length + 3)
+            },
+            set (newValue) {
+              this.lines = `:${this.name}: ${newValue}`.split('\n')
+            },
+          })
+          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) {
@@ -761,9 +848,9 @@ function processDocumentHeader (doc, lines, ignoreLines, isRootPage) {
   return entries
 }
 
-function generateSlug (string) {
+function generateDocname (string) {
   if (string === 'index') return string
-  return sanitizeSlug(
+  return sanitizeDocname(
     string
       .toLowerCase()
       .replace(/<[^>]+>/g, '')
@@ -776,8 +863,8 @@ function generateSlug (string) {
   )
 }
 
-function sanitizeSlug (slug) {
-  return slug.replace(/[^\p{Alpha}0-9_.-]/gu, '-').replace(/^-+|-+$|(-)-+/g, '$1')
+function sanitizeDocname (docname) {
+  return docname.replace(/[^\p{Alpha}0-9_.-]/gu, '-').replace(/^-+|-+$|(-)-+/g, '$1')
 }
 
 function fixSectionLevels (sections, expectedLevel) {
@@ -788,33 +875,29 @@ function fixSectionLevels (sections, expectedLevel) {
   })
 }
 
-// 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 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}`
+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
+  }
+  syntheticIds[id] = true
+  return id
 }
 
 module.exports = produceAssemblyFile