@antora/assembler 1.0.0-beta.8 → 1.0.0-rc.1

package/lib/produce-assembly-file.js

@@ -1,15 +1,32 @@
 'use strict'
 
-const createAsciiDocFile = require('./util/create-asciidoc-file')
-const path = require('node:path/posix')
+const createResourceKey = require('./util/create-resource-key')
+const generateScopedId = require('./util/generate-scoped-id')
+const { resolveLinkTarget } = require('./util/resolver')
+const {
+  rewriteXrefs,
+  rewriteImageAttr,
+  rewriteImageRef,
+  rewriteInlineImages,
+  rewriteStyleAttribute,
+} = require('./util/rewriter')
 const sanitize = require('./util/sanitize')
 const unconvertInlineAsciiDoc = require('./util/unconvert-inline-asciidoc')
 
-const AttributeEntryRx = /^:([^:-][^:]*):(?: .*)?$/
-const BuiltInNamedEntities = { amp: '&', apos: "'", gt: '>', lt: '<', nbsp: ' ', quot: '"' }
-const CharRefRx = /&(?:([a-z][a-z]+\d{0,2})|#(?:(\d{2,6})|x([a-z\d]{2,5})));/g
-const DiscardAttributes = 'doctype leveloffset assembly-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 = [
+  'doctype',
+  'leveloffset',
+  'preface-title',
+  'assembly-header-attributes',
+  'assembly-navtitle',
+  'assembly-slug',
+  'assembly-style',
+  'underscore',
+]
+const { NAMED_ID_ATTR_RX } = require('./util/rx')
 
 function produceAssemblyFile (
   loadAsciiDoc,
@@ -23,7 +40,30 @@ function produceAssemblyFile (
 ) {
   const pagesByUrl = files.reduce((map, it) => (it.src.family === 'page' ? map.set(it.pub.url, it) : map), new Map())
   if (outline.urlType === 'internal' && !pagesByUrl.get(outline.url) && !(outline.items || []).length) return
-  const pagesInOutline = selectPagesInOutline(outline, pagesByUrl, componentVersion)
+  const pagesInOutline = selectPagesInOutline(outline, pagesByUrl)
+  const { rootLevel, xmlIds } = assemblyModel
+  const idSeparators = {
+    prefix:
+      'assembler-idprefix' in asciidocConfig.attributes ? (asciidocConfig.attributes['assembler-idprefix'] ?? '') : '_',
+    scope: xmlIds ? '---' : ':::',
+    coordinate: xmlIds ? '----' : ':',
+    generateIdFromTitle: generateIdFromTitle.bind(
+      loadAsciiDoc(
+        { contents: Buffer.alloc(0), src: { family: 'page', relative: 'generate-id-from-title.adoc' } },
+        undefined,
+        asciidocConfig
+      )
+    ),
+  }
+  const { name: component, version } = componentVersion
+  asciidocConfig = prepareAsciiDocConfig(
+    contentCatalog,
+    { component, version },
+    pagesInOutline,
+    asciidocConfig,
+    assemblyModel,
+    idSeparators
+  )
   const buffer = mergeAsciiDoc(
     loadAsciiDoc,
     contentCatalog,
@@ -32,61 +72,87 @@ function produceAssemblyFile (
     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 =
+    (buffer.slug ? sanitizeSlug(buffer.slug) : generateSlug(rootLevel === 0 ? 'index' : buffer.navtitle)) ||
+    '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',
-    },
+    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
+  delete file.out
+  return file
+}
+
+function prepareAsciiDocConfig (contentCatalog, ctx, pagesInOutline, asciidocConfig, assemblyModel, idSeparators) {
+  let attributesModified
+  const configShared = asciidocConfig.$shared
+  const sharedAttributes = asciidocConfig.attributes
+  if (!configShared) {
+    if (configShared == null) {
+      const assets = pagesInOutline.assembled.assets
+      for (const [name, val] of Object.entries(sharedAttributes)) {
+        if (!(typeof val === 'string' && ~val.indexOf(':'))) continue
+        let newVal
+        if (!name.endsWith('-image') || !(newVal = rewriteImageAttr(val, contentCatalog, assemblyModel, ctx, assets))) {
+          if (~(newVal = val).indexOf('image:')) {
+            newVal = rewriteInlineImages(newVal, contentCatalog, assemblyModel, ctx, assets)
+          }
+        }
+        if (newVal !== val) sharedAttributes[name] = newVal
+      }
+    }
+    for (const [name, val] of Object.entries(sharedAttributes)) {
+      if (!(typeof val === 'string' && ~val.indexOf(':'))) continue
+      if (~val.indexOf('xref:')) {
+        const newVal = rewriteXrefs(val, contentCatalog, assemblyModel, ctx, false, pagesInOutline, idSeparators)
+        if (newVal !== val) (attributesModified ??= {})[name] = newVal
+      }
+    }
+    if (configShared == null) Object.defineProperty(asciidocConfig, '$shared', { value: attributesModified == null })
+  }
+  return Object.assign({}, asciidocConfig, { attributes: Object.assign({}, sharedAttributes, attributesModified) })
 }
 
 function buildAsciiDocHeader (componentVersion, navtitle, assemblyModel) {
   const doctype = assemblyModel.doctype ?? 'book'
   const navtitlePlain = sanitize(navtitle)
   const navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
-  let doctitle = navtitleAsciiDoc
-  if (navtitlePlain !== componentVersion.title) doctitle = `${componentVersion.title}: ${doctitle}`
+  const doctitle = (componentVersion.title === navtitlePlain ? '' : componentVersion.title + ': ') + navtitleAsciiDoc
   const version = componentVersion.version === 'master' ? '' : componentVersion.version
+  const displayVersion = componentVersion.displayVersion
   const buffer = [
     `= ${doctitle}`,
-    ...(version ? [`:revnumber: ${version}`] : []),
+    ...(version ? [`:revnumber: ${displayVersion}`] : []),
     ...(doctype === 'article' ? [] : [`:doctype: ${doctype ?? 'book'}`]),
     ':underscore: _',
     // Q: should we pass these via the CLI so they cannot be modified?
     `:page-component-name: ${componentVersion.name}`,
     `:page-component-version:${version ? ' ' + version : ''}`,
     ':page-version: {page-component-version}',
-    `:page-component-display-version: ${componentVersion.displayVersion}`,
+    `:page-component-display-version: ${displayVersion}`,
     `:page-component-title: ${componentVersion.title}`,
   ]
   return Object.assign(buffer, { navtitle })
 }
 
-function selectPagesInOutline (outlineEntry, pagesByUrl, componentVersion, accum) {
+function selectPagesInOutline (outlineEntry, pagesByUrl, accum) {
   accum ??= Object.assign(new Map(), { assembled: { pages: new Map(), assets: new Set() } })
   const page = outlineEntry.urlType === 'internal' ? pagesByUrl.get(outlineEntry.url) : undefined
   if (page) {
-    if (page.src.component === componentVersion.name && page.src.version === componentVersion.version) {
-      accum.set(`${page.src.module === 'ROOT' ? '' : page.src.module + ':'}${page.src.relative}`, page)
-    }
-    accum.set(page.pub.url, page)
+    accum.set(createResourceKey(page.src), page)
+    accum.set(outlineEntry.url, page)
   }
-  for (const item of outlineEntry.items || []) selectPagesInOutline(item, pagesByUrl, componentVersion, accum)
+  for (const item of outlineEntry.items || []) selectPagesInOutline(item, pagesByUrl, accum)
   return accum
 }
 
@@ -98,6 +164,7 @@ function mergeAsciiDoc (
   outlineEntry,
   files,
   pagesInOutline,
+  idSeparators,
   asciidocConfig,
   mutableAttributes,
   assemblyModel,
@@ -110,94 +177,84 @@ function mergeAsciiDoc (
     buffer.inBody ??= false
     return buffer
   }
-  let navtitle = outlineEntry.content
+  let navtitle = outlineEntry.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 { 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 && doctype === 'book' && (supportsParts = true)
+  const atBookRoot = atDocumentRoot && !level && assemblyModel.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
     }
+    const isRootPage = atDocumentRoot && !level
     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 })
     )
     const doc = loadAsciiDoc(pageAsAsciiDoc, contentCatalog, asciidocConfig)
-    if (doc.hasAttribute('assembly-navtitle')) {
+    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')
+    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}`
+        if (rootLevel) {
+          const doctitle =
+            (componentVersion.title === navtitlePlain ? '' : componentVersion.title + ': ') + navtitleAsciiDoc
           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)
-      }
-    }
     // NOTE: in Antora, docname is relative src path from module without file extension
     const docname = doc.getAttribute('docname')
-    const docnameForId = docname.replace(/[/.]/g, '-')
-    const qualifyId = component !== componentVersion.name
-    let idScope = docnameForId
-    let idPrefix
-    if (qualifyId) {
-      idScope = [component, module_ === 'ROOT' ? '' : module_, idScope].join(idCoordinateSeparator)
-    } else if (module_ !== 'ROOT') {
-      idScope = module_ + idCoordinateSeparator + idScope
-    } else if (ReservedIdNames.includes(docnameForId)) {
-      idScope = idPrefix = idScope + idScopeSeparator
-    }
-    idPrefix ??= idScope + idScopeSeparator
+    const pageId = generateScopedId(page.src, componentVersion, idSeparators, filetype)
+    const pageIdLeader = pageId + idSeparators.scope
     let pageFragment = ''
-    let pageRoles = ''
+    let pageRoles = []
     let pageStyle = doc.getAttribute('assembly-style', '')
+    if (
+      !pageStyle &&
+      atBookRoot &&
+      rootLevel === 0 &&
+      assemblyModel.sectionMergeStrategy === 'fuse' &&
+      !doc.source_header_attributes['$key?']('assembly-style')
+    ) {
+      pageStyle = 'preface'
+    }
     let part
     if ((part = pageStyle === 'part')) {
       pageStyle = ''
       if (!supportsParts) part = undefined
     } else if ((part = pageStyle.endsWith('-part'))) {
-      pageStyle = pageStyle.slice(0, -5)
+      pageStyle = pageStyle.substring(0, pageStyle.length - 5)
       if (!supportsParts) part = undefined
     }
     let nextSectionLevel = 1
     const lines = doc.getSourceLines()
     const ignoreLines = []
-    buffer.inBody = true
+    if (!buffer.inBody) {
+      buffer.inBody = true
+      buffer.endHeaderIdx = buffer.length - 1
+    }
     buffer.push('')
     buffer.push(`:docname: ${docname}`)
     if (component !== lastComponentVersion.name) {
@@ -221,81 +278,153 @@ 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 headerHasBlockAttrs
+    if (doc.hasHeader()) {
+      for (const entry of processDocumentHeader(doc, lines, ignoreLines, isRootPage)) {
+        if (entry.type === 'author_line') {
+          buffer.splice(1, 0, entry.lines[0])
+          buffer.endHeaderIdx += 1
+        } else if (entry.type === 'attribute_entry') {
+          const name = entry.name
+          if (!entry.negated && !doc.isAttributeLocked(name)) {
+            let val, newVal
+            if (
+              name.endsWith('-image') &&
+              (val = doc.getAttribute(name)) &&
+              (newVal = rewriteImageAttr(val, contentCatalog, assemblyModel, page.src, assembled.assets))
+            ) {
+              if (newVal !== val) entry.lines = [`:${name}: ${newVal}`]
+            } else if (~(val = entry.lines.join('\n').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')
+            }
+          }
+          if (entry.promote) {
+            buffer.splice(buffer.endHeaderIdx + 1, 0, ...entry.lines)
+            buffer.endHeaderIdx += entry.lines.length
+          } else {
+            buffer.push(...entry.lines)
+          }
+        } else {
+          if (entry.type === 'attrlist') headerHasBlockAttrs = true
+          buffer.push(...entry.lines)
+        }
+      }
+      pageRoles = doc.getRoles()
+    }
+    if (roles.length) pageRoles = pageRoles.concat(roles[0] === 'page' ? roles.slice(1) : roles)
     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))
-      ) {
-        htitleAsciiDoc = unconvertInlineAsciiDoc(htitleOverride)
-        htitlePlain = sanitize(htitleOverride)
+      let notitle
+      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:')
+              htitleAsciiDoc = undefined
+            }
+          } else if (hasPrefaceTitleAttr && !(headerHasBlockAttrs || doc.hasSections())) {
+            buffer.splice(++buffer.endHeaderIdx, 0, `:preface-title: ${unconvertInlineAsciiDoc(htitleOverride)}`)
+            htitleAsciiDoc = undefined
+          } else {
+            htitleAsciiDoc = unconvertInlineAsciiDoc(htitleOverride)
+          }
+        }
       }
-      if (atDocumentRoot && pageStyle === 'preface' && htitlePlain === componentVersion.title) {
-        assemblyModel = Object.assign({}, assemblyModel, { sectionMergeStrategy: 'discrete' })
-      } else {
+      if (htitleAsciiDoc != null) {
         if (atDocumentRoot) {
-          pageFragment = `#${idPrefix}${doc.getId() ?? pageStyle}`
-          buffer.unshift(`[#${idScope}]`)
+          // NOTE use pageStyle as fallback because this section must have a unique ID
+          pageFragment = `#${pageIdLeader}${doc.getId() ?? pageStyle}`
+          buffer.unshift(`[#${pageId}]`)
         } else {
-          pageFragment = `#${idScope}`
+          pageFragment = `#${pageId}`
         }
         heading = { title: htitleAsciiDoc, level: part ? 1 : 2 }
-        nextSectionLevel++
+        if (notitle) heading.notitle = true
+        nextSectionLevel = 2 // next section level is 2, even for special part
       }
     } else if (level) {
-      if (atDocumentRoot && navtitlePlain === componentVersion.title) {
+      if (atDocumentRoot && rootLevel === 0 && navtitlePlain === componentVersion.title && !hasAssemblyNavtitleAttr) {
         level--
       } else {
-        pageFragment = `#${idScope}`
+        pageFragment = `#${pageId}`
         if (part && level === 1) level--
         if ((heading = { title: navtitleAsciiDoc, level: level + 1 }).level > 6) {
           Object.assign(heading, { level: 6, style: `discrete.h${heading.level}` })
         }
       }
+    } 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) {
-      buffer.push(`[${heading.style ?? pageStyle}${pageFragment}${pageRoles}]`)
+      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(`[#${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 {
+      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(':!sectids:')
-          toggleSectids = true
+          buffer.push(`[#${syntheticId}]`)
         }
+        buffer.push(`${'='.repeat(hlevel)} ${overviewTitle}`)
       }
-      let hlevel = level + 2
-      if (hlevel > 6) {
-        const blockStyle = `discrete.h${hlevel}`
-        hlevel = 6
-        buffer.push(syntheticId ? `[${blockStyle}#${syntheticId}]` : `[${blockStyle}]`)
-      } else if (syntheticId) {
-        buffer.push(`[#${syntheticId}]`)
-      }
-      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)
     }
+    assembled.pages.set(page, pageFragment)
+    if (doc.hasSections()) fixSectionLevels(doc.getSections(), nextSectionLevel)
     const allBlocks = doc.findBy({ traverse_documents: true }, (it) =>
       it.getContext() === 'document'
         ? it.getDocument().isNested()
@@ -366,7 +495,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,114 +507,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
-          }
-          if (!relativePart) {
-            // Q: should we validate the internal ID here?
-            return text && ~text.indexOf('=')
-              ? `xref:${idPrefix}${fragment}[${text}]`
-              : `<<${idPrefix}${fragment}${text ? ',' + text.replace(/\\]/g, ']') : ''}>>`
-          }
-          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, '-')
-          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 `<<${refid}${text ? ',' + text.replace(/\\]/g, ']') : ''}>>`
+        line = line.replace(/\[\[([\p{Alpha}_:][\p{Alpha}0-9_\-:.]*)(|, *.+?)\]\]/gu, (_, refid, text) => {
+          return `[[${pageIdLeader}${refid}${text}]]`
         })
       }
-      if (~line.indexOf('link:{attachmentsdir}/')) {
-        line = line.replace(/(?<![\\+])link:\{attachmentsdir\}\/([^\s[]+)\[(|.*?[^\\])\]/g, (m, relative, text) => {
-          const attachment =
-            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
     }
@@ -511,53 +557,43 @@ 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 = Object.entries(doc.source_header_attributes.$$smap)
     if (attributeEntries.length) {
       const resolvedAttributeEntries = attributeEntries.reduce(
         (accum, [name, val]) => {
@@ -569,7 +605,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
@@ -579,26 +615,13 @@ function mergeAsciiDoc (
       if (resolvedAttributeEntries.length > 1) safePush(buffer, resolvedAttributeEntries)
     }
   } else if (level) {
-    if (atDocumentRoot && navtitlePlain === componentVersion.title) {
+    if (atDocumentRoot && rootLevel === 0 && navtitlePlain === componentVersion.title) {
       buffer.inBody ??= false
       level--
     } else {
       buffer.inBody = true
       buffer.push('')
-      // NOTE: try to toggle sectids; otherwise, fallback to globally unique synthetic ID
-      // Q: should we unset docname, page-module, etc?
-      let toggleSectids, syntheticId
-      if (!('sectids' in asciidocConfig.attributes)) {
-        buffer.push(':!sectids:')
-        toggleSectids = true
-      } else if (typeof asciidocConfig.attributes.sectids === 'string') {
-        if ('sectids' in mutableAttributes) {
-          buffer.push(':!sectids:')
-          toggleSectids = true
-        } else {
-          syntheticId = `__object-id-${global.Opal.hash(outlineEntry).$object_id()}`
-        }
-      }
+      const syntheticId = idSeparators.generateIdFromTitle(navtitleAsciiDoc, idSeparators)
       let sectionTitle = navtitleAsciiDoc
       if (urlType === 'external') {
         sectionTitle = `${url}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
@@ -606,27 +629,19 @@ function mergeAsciiDoc (
         const resource = files.find((it) => it.pub.url === url)
         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}`
-            sectionTitle = `<<${refid},${navtitleAsciiDoc}>>`
+            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}]`)
-      }
+      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?
@@ -642,6 +657,7 @@ function mergeAsciiDoc (
         item,
         files,
         pagesInOutline,
+        idSeparators,
         asciidocConfig,
         mutableAttributes,
         assemblyModel,
@@ -654,11 +670,32 @@ function mergeAsciiDoc (
   return buffer
 }
 
-function processDocumentHeader (doc, lines, buffer, ignoreLines) {
+function processDocumentHeader (doc, lines, ignoreLines, isRootPage) {
+  const entries = []
+  let assemblyHeaderAttributes = isRootPage && doc.getAttribute('assembly-header-attributes', '%authors')
+  assemblyHeaderAttributes = new Set(assemblyHeaderAttributes ? assemblyHeaderAttributes.split(/, */) : undefined)
+  if (assemblyHeaderAttributes.size) {
+    if (assemblyHeaderAttributes.has('%authors')) {
+      const authors = doc.getAuthors()
+      if (authors.length) {
+        entries.push({
+          type: 'author_line',
+          promote: true,
+          lines: [
+            authors
+              .map((author) => (author.getEmail() ? `${author.getName()} <${author.getEmail()}>` : author.getName()))
+              .join('; '),
+          ],
+        })
+      }
+      assemblyHeaderAttributes.delete('%authors')
+    }
+    const headerAttributes = doc.source_header_attributes
+    for (const name of assemblyHeaderAttributes) headerAttributes.$delete(name)
+  }
   const doctitleIdx = doc.getHeader().getLineNumber() - 1
   const end = doc.getBlocks()[0]?.getLineNumber() ?? lines.length
-  let belowDoctitle
-  let open
+  let belowDoctitle, current, open
   const implicitLines = []
   for (let idx = 0; idx < end; idx++) {
     if (idx === doctitleIdx) {
@@ -669,41 +706,51 @@ function processDocumentHeader (doc, lines, buffer, ignoreLines) {
     }
     const line = lines[idx]
     if (open === ':' || open === '-:') {
-      if (line) {
-        if (open === ':') buffer.push(line)
-        if (!line.endsWith(' \\')) open = undefined
-      } else {
-        open = undefined
-      }
+      if (open === ':') current.lines.push(line)
+      if (!line?.endsWith(' \\')) current = open = undefined
     } else if (line) {
-      const chr0 = line.charAt()
       let attributeEntryMatch
+      const chr0 = line.charAt()
       if (chr0 === '/' && line.charAt(1) === '/') {
-        if (line.startsWith('////')) {
-          open = open ? (open === line ? undefined : open) : line
-        } else if (belowDoctitle && !open && line.charAt(2) === '/') {
+        if (line.startsWith('////') && line === '/'.repeat(line.length)) {
+          if (open) {
+            current.lines.push(line)
+            if (open === line) current = open = undefined
+          } else {
+            entries.push((current = { type: 'block_comment', lines: [(open = line)] }))
+          }
+        } else if (open) {
+          current.lines.push(line)
+        } else if (belowDoctitle && line.charAt(2) === '/') {
           break
+        } else {
+          entries.push({ type: 'line_comment', lines: [line] })
+          current = undefined
         }
-        buffer.push(line)
       } else if (open) {
-        buffer.push(line)
-      } else if (chr0 === ':' && ~line.indexOf(':', 2) && (attributeEntryMatch = line.match(AttributeEntryRx))) {
-        const attributeName = attributeEntryMatch[1].replace('!', '')
-        if (DiscardAttributes.includes(attributeName)) {
-          if (line.endsWith(' \\')) open = '-:'
+        current.lines.push(line)
+      } else if (chr0 === ':' && ~line.indexOf(':', 2) && (attributeEntryMatch = line.match(ATTR_ENTRY_RX))) {
+        let name = attributeEntryMatch[1]
+        const negated = name.charAt() === '!' || name.charAt(name.length - 1) === '!'
+        if (negated) name = name.replace('!', '')
+        if (DISCARD_ATTRIBUTE_NAMES.includes(name) && !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: [line], lineno: idx + 1 }))
+          if (assemblyHeaderAttributes.has(name)) current.promote = true
         }
       } else if (belowDoctitle) {
         if (implicitLines.length === 2 || !/[\p{Alpha}0-9]/u.test(chr0)) break
         implicitLines.push(line)
       } else if (chr0 === '[' && line.charAt(line.length - 1) === ']') {
+        current = undefined
         const attrlist = line
-          .slice(1, -1)
+          .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
@@ -711,23 +758,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) {
@@ -738,64 +788,6 @@ 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)
@@ -818,35 +810,11 @@ function safePush (onto, entries) {
   }
 }
 
-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)]
-    }
-  }
-  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
+function generateIdFromTitle (titleAsciiDoc, idSeparators) {
+  const Section = this.$class().$const_get('::Asciidoctor::Section')
+  const baseId = Section.$generate_id(titleAsciiDoc, this)
+  this.getCatalog().refs['$[]='](baseId, true)
+  return `_${idSeparators.coordinate}${baseId}`
 }
 
 module.exports = produceAssemblyFile