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

package/lib/produce-aggregate-document.js

@@ -1,13 +1,15 @@
 'use strict'
 
-const File = require('vinyl')
-const { posix: path } = require('path')
+const path = require('node:path/posix')
+const sanitize = require('./util/sanitize')
+const unconvertInlineAsciiDoc = require('./util/unconvert-inline-asciidoc')
 
 function produceAggregateDocument (
   loadAsciiDoc,
   contentCatalog,
   componentVersion,
   outline,
+  doctype,
   pages,
   asciidocConfig,
   mutableAttributes,
@@ -15,8 +17,19 @@ function produceAggregateDocument (
 ) {
   const pagesInOutline = selectPagesInOutline(outline, pages)
   const navtitle = outline.content
-  const stem = generateStem(componentVersion, navtitle)
-  const header = buildAsciiDocHeader(componentVersion, navtitle)
+  const templateFile = contentCatalog.addFile({
+    src: {
+      component: componentVersion.name,
+      version: componentVersion.version,
+      module: 'ROOT',
+      family: 'page',
+      relative: generateSlug(navtitle),
+    },
+  })
+  const { dir: outDir, name: outName } = path.parse(templateFile.out.path)
+  const path_ = outName === templateFile.src.relative ? path.join(outDir, outName + '.adoc') : outDir + '.adoc'
+  contentCatalog.removeFile(templateFile)
+  const header = buildAsciiDocHeader(componentVersion, navtitle, doctype)
   const body = aggregateAsciiDoc(
     loadAsciiDoc,
     contentCatalog,
@@ -28,29 +41,33 @@ function produceAggregateDocument (
     mutableAttributes,
     sectionMergeStrategy
   )
-  const relativeSrcPath = `${stem}.adoc`
-  return new File({
+  return new templateFile.constructor({
+    aggregate: true,
     asciidoc: asciidocConfig,
     contents: Buffer.from([...header, ...body].join('\n') + '\n'),
     mediaType: 'text/asciidoc',
-    path: relativeSrcPath,
+    path: path_,
     src: {
       component: componentVersion.name,
       version: componentVersion.version,
-      basename: path.basename(relativeSrcPath),
-      stem,
+      basename: path.basename(path_),
+      stem: path.basename(path_, '.adoc'),
       extname: '.adoc',
     },
   })
 }
 
-function buildAsciiDocHeader (componentVersion, navtitle) {
-  const doctitle = navtitle === componentVersion.title ? navtitle : `${componentVersion.title}: ${navtitle}`
-  const version = componentVersion.version && componentVersion.version !== 'master' ? componentVersion.version : ''
+function buildAsciiDocHeader (componentVersion, navtitle, doctype = 'book') {
+  const navtitlePlain = sanitize(navtitle)
+  const navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
+  let doctitle = navtitleAsciiDoc
+  if (navtitlePlain !== componentVersion.title) doctitle = `${componentVersion.title}: ${doctitle}`
+  const version = componentVersion.version === 'master' ? '' : componentVersion.version
   return [
     `= ${doctitle}`,
-    ...(version ? [`v${version}`] : []),
-    ':doctype: book', // for debugging only; set via CLI
+    ...(version ? [`:revnumber: ${version}`] : []),
+    ...(doctype === 'article' ? [] : [`:doctype: ${doctype}`]),
+    ':underscore: _',
     // Q: should we pass these via the CLI so they cannot be modified?
     `:page-component-name: ${componentVersion.name}`,
     `:page-component-version:${version ? ' ' + version : ''}`,
@@ -63,7 +80,7 @@ function buildAsciiDocHeader (componentVersion, navtitle) {
 function selectPagesInOutline (outlineEntry, pages) {
   const page = outlineEntry.urlType === 'internal' ? pages.find((it) => it.pub.url === outlineEntry.url) : undefined
   return (outlineEntry.items || []).reduce(
-    (accum, item) => new Map([...accum, ...selectPagesInOutline(item, pages)]),
+    (accum, item) => selectPagesInOutline(item, pages).forEach((v, k) => accum.set(k, v)) ?? accum,
     new Map(
       page && [
         [`${page.src.module === 'ROOT' ? '' : page.src.module + ':'}${page.src.relative}`, page],
@@ -83,16 +100,26 @@ function aggregateAsciiDoc (
   asciidocConfig,
   mutableAttributes,
   sectionMergeStrategy,
+  lastComponentVersion = componentVersion,
   level = 0
 ) {
   const buffer = []
   // TODO: we could try to be smart about it and make sure the page with fragment is included at least once
   if (outlineEntry.hash) return buffer
-  const { content: navtitle, items, unresolved, urlType, url } = outlineEntry
+  const { content: navtitle, items = [], unresolved, urlType, url } = outlineEntry
+  const hasItems = items.length > 0
+  const navtitlePlain = sanitize(navtitle)
+  const navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
+  const siteUrl = ((val) => {
+    if (!val || val === '/') return ''
+    return val.charAt(val.length - 1) === '/' ? val.slice(0, val.length - 1) : val
+  })(asciidocConfig.attributes['site-url'])
   // FIXME: ideally, resource ID would be stored in navigation so we can look up the page more efficiently
   let page = urlType === 'internal' && !unresolved ? pagesInOutline.get(url) : undefined
+  if (page && pagesInOutline.aggregated?.includes(page)) page = undefined
   if (page) {
     let contents = page.src.contents
+    if (contents == null) return buffer
     // NOTE: blank lines at top and bottom of document create mismatch when using line numbers to navigate source lines
     // IMPORTANT: this must not leave behind lines the parser will drop!
     // IDEA: another option is to capture initial lineno of reader and use as offset (but preseves those blank lines)
@@ -102,17 +129,37 @@ function aggregateAsciiDoc (
         .replace(/^(?:[ \t]*\r\n?|[ \t]*\n)+/, '')
         .trimRight()
     )
+    ;(pagesInOutline.aggregated ??= []).push(page)
     page = new page.constructor(Object.assign({}, page, { contents, mediaType: 'text/asciidoc' }))
-    const { module: module_, relative, origin } = page.src
+    const { component, version, module: module_, relative, origin } = page.src
+    const topicPrefix = ~relative.indexOf('/') ? path.dirname(relative) + '/' : ''
     const doc = loadAsciiDoc(page, contentCatalog, asciidocConfig)
-    const ids = doc.getCatalog().ids
+    const refs = doc.getCatalog().refs
     // NOTE: in Antora, docname is relative src path from module without file extension
     const docname = doc.getAttribute('docname')
-    //const idprefix = `${module_ === 'ROOT' ? '' : module_ + ':'}${docname}//`
-    const idprefix = `${module_ === 'ROOT' ? '' : module_ + ':'}${docname.replace(/[/]/g, '::')}:::`
-    //const idprefix = `${module_ === 'ROOT' ? '' : module_ + ':'}${docname.replace(/[/]/g, ':-:')}:--:`
+    const docnameForId = docname.replace(/[/]/g, '::').replace(/[.]/g, '-')
+    const scopeId = component !== componentVersion.name
+    const idprefix =
+      (scopeId ? component + ':' : '') +
+      (module_ === 'ROOT' ? (scopeId ? ':' : '') : module_ + ':') +
+      docnameForId +
+      ':::'
     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-type: ${origin.type}`)
@@ -124,7 +171,7 @@ function aggregateAsciiDoc (
     let enclosed
     // NOTE: if level is 0, doctitle has already been added and we're in the document header
     if (level) {
-      if (level === 1 && navtitle === componentVersion.title) {
+      if (level === 1 && navtitlePlain === componentVersion.title) {
         level--
       } else {
         let hlevel = level + 1
@@ -134,12 +181,12 @@ function aggregateAsciiDoc (
         } else {
           buffer.push(`[#${idprefix}]`)
         }
-        buffer.push(`${'='.repeat(hlevel)} ${navtitle}`)
+        buffer.push(`${'='.repeat(hlevel)} ${navtitleAsciiDoc}`)
       }
     } else {
       header.unshift(`[#${idprefix}]`)
     }
-    if (sectionMergeStrategy === 'enclose' && items && doc.hasSections()) {
+    if (sectionMergeStrategy === 'enclose' && hasItems && doc.hasSections()) {
       enclosed = true
       // TODO: make overview section title configurable
       //let overviewTitle = doc.getDocumentTitle()
@@ -166,27 +213,15 @@ function aggregateAsciiDoc (
       buffer.push(`${'='.repeat(hlevel)} ${overviewTitle}`)
       if (toggleSectids) buffer.push(':sectids:')
     }
-    const siteUrl = doc.getAttribute('site-url')
     const lines = doc.getSourceLines()
     const ignoreLines = []
     // TODO: think more about when multipart is allowed; perhaps configurable
     if (doc.hasSections()) fixSectionLevels(doc.getSections(), level === 0)
-    // TODO: update / simplify findBy calls when upgrading to Asciidoctor 2
-    const allBlocks = doc
-      .findBy((it) => it.getContext() !== 'document')
-      .reduce((accum, block) => {
-        accum.push(block)
-        if (block.getContext() === 'table') {
-          const rows = block.rows
-          ;[...rows.body, ...rows.foot].forEach((row) => {
-            row.forEach((cell) => {
-              if (cell.style !== 'asciidoc') return
-              accum.push(...cell.inner_document.findBy((it) => it.getContext() !== 'document'))
-            })
-          })
-        }
-        return accum
-      }, [])
+    const allBlocks = doc.findBy({ traverse_documents: true }, (it) =>
+      it.getContext() === 'document'
+        ? it.getDocument().isNested()
+        : !(it.getContext() === 'table_cell' && it.getStyle() === 'asciidoc')
+    )
     allBlocks.forEach((block) => {
       const contentModel = block.content_model
       if (
@@ -213,16 +248,33 @@ function aggregateAsciiDoc (
         for (let i = idx; i < block.lines.length + (delimited ? idx + 2 : idx); i++) ignoreLines.push(i)
       }
     })
+    let skipping
     for (let idx = 0, len = lines.length; idx < len; idx++) {
       if (~ignoreLines.indexOf(idx)) continue
       let line = lines[idx]
+      if (line.startsWith('//')) {
+        if (line[2] !== '/') continue
+        if (line.length > 3 && line === '/'.repeat(line.length)) {
+          if (skipping) {
+            if (line === skipping) skipping = undefined
+          } else {
+            skipping = line
+          }
+          continue
+        }
+      } else if (skipping) {
+        continue
+      }
+      if (line.charAt() === ':' && /^:(?:leveloffset: .*|!leveloffset:|leveloffset!:)$/.test(line)) {
+        if (lines[idx - 1] === '') lines[idx - 1] = undefined
+        lines[idx] = undefined
+        continue
+      }
       if (~line.indexOf('<<')) {
         line = line.replace(/(?<![\\+])<<#?([\p{Alpha}0-9_/.:{][^>,]*?)(?:|, *([^>]+?))?>>/gu, (m, refid, text) => {
-          // support natural xref; note this logic will change when upgrading to Asciidoctor 2
-          if (!ids['$key?'](refid) && (~refid.indexOf(' ') || refid.toLowerCase() !== refid)) {
-            if (!(refid = doc.getCatalog().ids.$key(refid).$to_s())) {
-              return m
-            }
+          // support natural xref
+          if (!refs['$key?'](refid) && (~refid.indexOf(' ') || refid.toLowerCase() !== refid)) {
+            if ((refid = doc.$resolve_id(refid))['$nil?']()) return m
           }
           return `<<${idprefix}${refid}${text ? ',' + text : ''}>>`
         })
@@ -233,38 +285,56 @@ function aggregateAsciiDoc (
       }
       if (~line.indexOf('xref:')) {
         // Q: should we allow : as first character of target?
-        line = line.replace(/xref:([\p{Alpha}#/.{].*?)\[(|.*?[^\\])\]/gu, (m, target, text) => {
+        line = line.replace(/(?<![\\+])xref:((?:\.\/)?[\p{Alpha}0-9_/.{#].*?)\[(|.*?[^\\])\]/gu, (m, target, text) => {
           let pagePart, fragment, targetPage
           const hashIdx = target.indexOf('#')
           if (~hashIdx) {
-            pagePart = target.substr(0, hashIdx)
-            fragment = target.substr(hashIdx + 1)
+            pagePart = target.slice(0, hashIdx)
+            fragment = target.slice(hashIdx + 1)
             // TODO: for now, assume .adoc; in the future, consider other file extensions
-            if (!(pagePart && pagePart.endsWith('.adoc'))) pagePart += '.adoc'
+            if (pagePart && !pagePart.endsWith('.adoc')) pagePart += '.adoc'
           } else if (target.endsWith('.adoc')) {
             pagePart = target
             fragment = ''
           } else {
             fragment = target
           }
-          if (!pagePart) return `<<${idprefix}${fragment}${text ? ',' + text.replace(/\\]/g, ']') : ''}>>`
+          if (!pagePart) {
+            // Q: should we validate the internal ID here?
+            return text && ~text.indexOf('=')
+              ? `xref:${idprefix}${fragment}[${text}]`
+              : `<<${idprefix}${fragment}${text ? ',' + text.replace(/\\]/g, ']') : ''}>>`
+          }
           if (~pagePart.indexOf('@') || /:.*:/.test(pagePart)) {
+            if (siteUrl && (targetPage = contentCatalog.resolvePage(pagePart, page.src)) && targetPage.out) {
+              text ||= targetPage.asciidoc?.xreftext || target
+              return `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
+            }
             // TODO: handle unresolved page better
-            return siteUrl && (targetPage = contentCatalog.resolvePage(pagePart, page.src))
-              ? `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
-              : m
-          } else if (pagePart.indexOf(':') < 0) {
-            if (module_ !== 'ROOT') pagePart = `${module_}:${pagePart}`
-          } else if (pagePart.startsWith('ROOT:')) {
-            pagePart = pagePart.substr(5)
+            return m
+          }
+          let targetModule
+          const colonIdx = pagePart.indexOf(':')
+          if (~colonIdx) {
+            targetModule = pagePart.slice(0, colonIdx)
+            pagePart = pagePart.slice(colonIdx + 1)
+          } else {
+            targetModule = module_
           }
+          if (pagePart.startsWith('./')) pagePart = topicPrefix + pagePart.slice(2)
+          if (targetModule !== 'ROOT') pagePart = `${targetModule}:${pagePart}`
           if (!(targetPage = pagesInOutline.get(pagePart))) {
+            if (siteUrl && (targetPage = contentCatalog.resolvePage(pagePart, page.src)) && targetPage.out) {
+              text ||= targetPage.asciidoc?.xreftext || target
+              return `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
+            }
             // TODO: handle unresolved page better
-            return siteUrl && (targetPage = contentCatalog.resolvePage(target, page.src))
-              ? `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
-              : m
+            return m
           }
-          pagePart = pagePart.replace(/[/]/g, '::').replace(/\.adoc$/, '')
+          pagePart = pagePart
+            .replace(/[/]/g, '::')
+            .replace(/\.adoc$/, '')
+            .replace(/[.]/g, '-')
           const refid = `${pagePart}:::${fragment}`
           return `<<${refid}${text && text !== targetPage.title ? ',' + text.replace(/\\]/g, ']') : ''}>>`
         })
@@ -280,7 +350,8 @@ function aggregateAsciiDoc (
               family: 'attachment',
               relative,
             })
-          return attachment ? `${siteUrl}${attachment.pub.url}[${text}]` : m
+          // TODO: handle unresolved attachment page
+          return attachment?.out ? `${siteUrl}${attachment.pub.url.replace(/_/g, '{underscore}')}[${text}]` : m
         })
       }
       if (~line.indexOf('image:') && !line.startsWith('image::')) {
@@ -288,9 +359,9 @@ function aggregateAsciiDoc (
           if (isResourceSpec(target)) {
             const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
             // TODO: handle (or report) unresolved image better
-            if (image) {
+            if (image?.out) {
               image.out.assembled = true
-              return `image:${image.pub.url.substr(1)}[${attrlist}]`
+              return `image:${image.out.path.replace(/_/g, '{underscore}')}[${attrlist}]`
             }
           }
           return m
@@ -301,66 +372,69 @@ function aggregateAsciiDoc (
     // NOTE: need to do this last since it modifies the line numbers
     // we could remap the line numbers to make them resilient
     // or we could mark which lines to remove and filter them after
+    let lastImageMacroAt
     ;[...allBlocks].reverse().forEach((block) => {
       const lineno = block.getLineNumber()
       // NOTE: lineno is not defined for preamble
       if (typeof lineno !== 'number') return
       const context = block.getContext()
-      const idx = lineno - 1
-      if (context === 'section') {
+      let idx = lineno - 1
+      if (context === 'section' && !block.getDocument().isNested()) {
         if (block.getSectionName() === 'header') {
-          lines.splice(idx, 1)
+          lines[idx] = undefined
           return
         }
         let blockStyle = sectionMergeStrategy === 'discrete' ? 'discrete' : undefined
-        // FIXME: quick fix; needs more thorough review
-        const leveloffset = Number(doc.getAttribute('leveloffset') || 0)
-        lines[idx] = lines[idx].replace(/^=+( .+)/, (_, rest) => {
-          let targetMarkerLength = block.level + (1 - leveloffset) + level + (enclosed ? 1 : 0)
+        lines[idx] = lines[idx].replace(/^=+ (.+)/, (_, rest) => {
+          let targetMarkerLength = block.level + 1 + level + (enclosed ? 1 : 0)
           if (targetMarkerLength > 6) {
             targetMarkerLength = 6
             blockStyle = 'discrete'
           }
-          return '='.repeat(targetMarkerLength) + rest
+          return '='.repeat(targetMarkerLength) + ' ' + rest
         })
         // NOTE: ID will be undefined if sectids are turned off
         if (block.getId()) rewriteStyleAttribute(block, lines, idx, idprefix, blockStyle)
       } else {
         if (context === 'image') {
-          const atImageMacro = (lines[idx] || '').startsWith('image::')
-          // NOTE: the following logic is needed only if parser is messing up line number of image block
-          //let atImageMacro
-          //// NOTE: account for line number tracking error in parser when image has block anchor
-          //if (block.getId()) {
-          //  const originalIdx = idx
-          //  let line
-          //  while ((line = lines[idx]) != null && !(atImageMacro = line.startsWith('image::'))) idx++
-          //  if (!atImageMacro) {
-          //    idx = originalIdx
-          //    if ((lines[idx - 1] || '').startsWith('image::')) {
-          //      atImageMacro = true
-          //      idx--
-          //    }
-          //  }
-          //} else if ((lines[idx] || '').startsWith('image::')) {
-          //  atImageMacro = true
-          //}
-          const target = block.getAttribute('target')
-          if (atImageMacro && isResourceSpec(target)) {
-            const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
-            // FIXME: handle (or report) case when image is not resolved
-            if (image) {
-              image.out.assembled = true
-              const line = lines[idx]
-              lines[idx] = `image::${image.pub.url.substr(1)}${line.substr(line.indexOf('['))}`
+          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
+          ).lastIndexOf('image::')
+          if (imageMacroOffset > 0) {
+            if (
+              block.getDocument().isNested() &&
+              (prefix = line.slice(0, imageMacroOffset)).trimRight().endsWith('|')
+            ) {
+              line = line.slice(prefix.length)
+            } else {
+              imageMacroOffset = -1
+            }
+          }
+          if (imageMacroOffset >= 0) {
+            const target = block.getAttribute('target')
+            if (isResourceSpec(target)) {
+              const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
+              // FIXME: handle (or report) case when image is not resolved
+              if (image?.out) {
+                const boxedAttrlist = line.slice(line.indexOf('['))
+                image.out.assembled = true
+                lines[idx] = `${prefix}image::${image.out.path}${boxedAttrlist}`
+              }
             }
+            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)
       }
     })
-    buffer.push(...lines)
-    const attributeEntries = Object.entries(doc.attributes_defined_in_header || {})
+    buffer.push(...lines.filter((it) => it !== undefined))
+    const attributeEntries = Object.entries(doc.source_header_attributes?.$$smap || {})
     if (attributeEntries.length) {
       const resolvedAttributeEntries = attributeEntries.reduce(
         (accum, [name, val]) => {
@@ -372,7 +446,15 @@ function aggregateAsciiDoc (
             } else if (val !== initialVal) {
               accum.push(`:${name}:${initialVal ? ' ' + initialVal : ''}`)
             }
-          } else if (val != null && !doc.isAttributeLocked(name)) {
+          } else if (
+            !(
+              val == null ||
+              doc.isAttributeLocked(name) ||
+              name === 'doctype' ||
+              name === 'leveloffset' ||
+              name === 'underscore'
+            )
+          ) {
             accum.push(`:!${name}:`)
           }
           return accum
@@ -381,43 +463,51 @@ function aggregateAsciiDoc (
       )
       if (resolvedAttributeEntries.length > 1) buffer.push(...resolvedAttributeEntries)
     }
-  } else {
-    if (level) {
-      if (level === 1 && navtitle === componentVersion.title) {
-        level--
-      } else {
-        buffer.push('')
-        // NOTE: try to toggle sectids; otherwise, fallback to globally unique synthetic ID
-        let toggleSectids, syntheticId
-        if (!('sectids' in asciidocConfig.attributes)) {
+  } else if (level) {
+    if (level === 1 && navtitlePlain === componentVersion.title) {
+      level--
+    } else {
+      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 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()}`
-          }
-        }
-        // Q: should we unset docname, page-module, etc?
-        const sectionTitle = urlType === 'external' ? `${url}[${navtitle.replace(/\]/, '\\]')}]` : navtitle
-        let hlevel = level + 1
-        if (hlevel > 6) {
-          hlevel = 6
-          buffer.push(syntheticId ? `[discrete#${syntheticId}]` : '[discrete]')
-        } else if (syntheticId) {
-          buffer.push(`[#${syntheticId}]`)
+        } else {
+          syntheticId = `__object-id-${global.Opal.hash(outlineEntry).$object_id()}`
         }
-        buffer.push(`${'='.repeat(hlevel)} ${sectionTitle}`)
-        if (toggleSectids) buffer.push(':sectids:')
       }
+      let sectionTitle = navtitleAsciiDoc
+      if (urlType === 'external') {
+        sectionTitle = `${url}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+      } else if (urlType === 'internal' && !unresolved && siteUrl) {
+        const resource = contentCatalog.getFiles().find((it) => it.out && it.pub.url === url)
+        if (resource) sectionTitle = `${siteUrl}${resource.pub.url}[${navtitleAsciiDoc.replace(/\]/g, '\\]')}]`
+      }
+      let hlevel = level + 1
+      if (hlevel > 6) {
+        hlevel = 6
+        buffer.push(syntheticId ? `[discrete#${syntheticId}]` : '[discrete]')
+      } else if (syntheticId) {
+        buffer.push(`[#${syntheticId}]`)
+      }
+      buffer.push(`${'='.repeat(hlevel)} ${sectionTitle}`)
+      if (toggleSectids) buffer.push(':sectids:')
     }
   }
 
   const nextLevel = level + 1
-  if (items) {
-    items.forEach((item) => {
+  if (hasItems) {
+    // 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) => {
       buffer.push(
         ...aggregateAsciiDoc(
           loadAsciiDoc,
@@ -429,6 +519,7 @@ function aggregateAsciiDoc (
           asciidocConfig,
           mutableAttributes,
           sectionMergeStrategy,
+          lastComponentVersion,
           nextLevel
         )
       )
@@ -437,18 +528,12 @@ function aggregateAsciiDoc (
   return buffer
 }
 
-function generateStem (componentVersion, title) {
-  const { name, version } = componentVersion
-  const segments = [name]
-  if (version && version !== 'master') segments.push(version)
-  segments.push(
-    title
-      .toLowerCase()
-      .replace(/&.+?;|[^ \p{Alpha}0-9_\-.]/gu, '')
-      .replace(/[ _.]/g, '-')
-      .replace(/--+/g, '-')
-  )
-  return path.join(...segments)
+function generateSlug (title) {
+  return title
+    .toLowerCase()
+    .replace(/&.+?;|[^ \p{Alpha}0-9_\-.]/gu, '')
+    .replace(/[ _.]/g, '-')
+    .replace(/--+/g, '-')
 }
 
 function fixSectionLevels (sections, multipart) {
@@ -485,10 +570,10 @@ function rewriteStyleAttribute (block, lines, idx, idprefix, replacementStyle =
     let rawStyle
     const commaIdx = prevLine.indexOf(',')
     if (~commaIdx) {
-      rawStyle = prevLine.substr(1, commaIdx - 1)
+      rawStyle = prevLine.slice(1, commaIdx)
       if (~rawStyle.indexOf('=')) rawStyle = undefined
     } else if (!~prevLine.indexOf('=')) {
-      rawStyle = prevLine.substr(1, prevLine.length - 2)
+      rawStyle = prevLine.slice(1, prevLine.length - 1)
     }
     if (rawStyle) {
       if (~rawStyle.indexOf('#')) {
@@ -496,11 +581,11 @@ function rewriteStyleAttribute (block, lines, idx, idprefix, replacementStyle =
         if (replacementStyle) prevLine = prevLine.replace(/^[^#.%,\]]+/, `[${replacementStyle}`)
       } else {
         prevLine = `[${
-          replacementStyle ? rawStyle.replace(/^[^.%]*]/, replacementStyle) : rawStyle
-        }#${idprefix}${block.getId()}${prevLine.substr(rawStyle.length + 1)}`
+          replacementStyle ? rawStyle.replace(/^[^.%]*/, replacementStyle) : rawStyle
+        }#${idprefix}${block.getId()}${prevLine.slice(rawStyle.length + 1)}`
       }
     } else {
-      prevLine = `[${replacementStyle}#${idprefix}${block.getId()}${rawStyle == null ? ',' : ''}${prevLine.substr(1)}`
+      prevLine = `[${replacementStyle}#${idprefix}${block.getId()}${rawStyle == null ? ',' : ''}${prevLine.slice(1)}`
     }
     if (cellSpec) prevLine = `${cellSpec}|${prevLine}`
     lines[idx - 1] = prevLine