@antora/assembler 1.0.0-rc.10 → 1.0.0-rc.12

package/lib/produce-assembly-file.js

@@ -18,12 +18,13 @@ const ATTR_ENTRY_RX = /^:(!?[\p{Alpha}0-9_][^:]*):(?: |$)/u
 const BUILT_IN_NAMED_ENTITIES = { amp: '&', apos: "'", gt: '>', lt: '<', nbsp: ' ', quot: '"' }
 const CHAR_REF_RX = /&(?:([a-z][a-z]+\d{0,2})|#(?:(\d{2,6})|x([a-z\d]{2,5})));/g
 const DISCARD_ATTRIBUTE_NAMES = [
+  'assembly-docname',
+  'assembly-doctitle',
   'assembly-doctype',
   'assembly-header-attributes',
   'assembly-overview-title',
   'assembly-navtitle',
   'assembly-root-title',
-  'assembly-slug',
   'assembly-style',
   'doctype',
   'leveloffset',
@@ -88,7 +89,9 @@ function produceAssemblyFile (
     assemblyModel
   )
   const stem =
-    (builder.slug ? sanitizeSlug(builder.slug) : generateSlug(rootLevel === 0 ? 'index' : builder.baseDoctitle)) ||
+    (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({
@@ -147,7 +150,7 @@ function buildAssemblyHeader (componentVersion, navtitle, assemblyModel) {
   const { name: componentName, version, displayVersion, title } = componentVersion
   const navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
   const navtitlePlain = sanitize(navtitle)
-  const doctitleQualifier = assemblyModel.rootLevel === 0 ? '' : title
+  const doctitleQualifier = assemblyModel.rootLevel === 0 ? undefined : title
   const versioned = !!(version && version !== 'master')
   return {
     header: [
@@ -168,10 +171,10 @@ function buildAssemblyHeader (componentVersion, navtitle, assemblyModel) {
     setAuthor (author) {
       this.header.splice(1, 0, author)
     },
-    setDoctitle (doctitle, doctitleAsciiDoc, doctitlePlain) {
+    updateDoctitle (doctitle, doctitleAsciiDoc, doctitlePlain, useQualifier = true) {
       this.baseDoctitle = doctitle
       this.baseDoctitlePlain = doctitlePlain
-      const qualifyDoctitle = this.doctitleQualifier ? this.doctitleQualifier !== doctitlePlain : false
+      const qualifyDoctitle = useQualifier && !!this.doctitleQualifier && this.doctitleQualifier !== doctitlePlain
       this.header[0] = `= ${qualifyDoctitle ? this.doctitleQualifier + ': ' : ''}${doctitleAsciiDoc}`
     },
     matchesDoctitle (candidate) {
@@ -229,15 +232,20 @@ function mergeAsciiDoc (
     return builder
   }
   const assembled = pagesInOutline.assembled
+  const atStartOfBody = !builder.body?.length
+  const isRootEntry = atStartOfBody && !level
   // 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(pathname) : undefined
-  let navtitle = outlineEntry.navtitle ?? (page && hash ? page.asciidoc.navtitle : outlineEntry.content)
+  let navtitle = outlineEntry.content
+  if (isRootEntry && 'navtitle' in outlineEntry) {
+    navtitle = outlineEntry.navtitle
+  } else if (page && hash) {
+    navtitle = page.asciidoc.navtitle
+  }
   let navtitleAsciiDoc = unconvertInlineAsciiDoc(navtitle)
   let navtitlePlain = sanitize(navtitle)
-  const { doctype, filetype, linkReferenceStyle, pubRoot, siteRoot, logger, rootPageStyle } = assemblyModel
+  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)) {
@@ -256,22 +264,32 @@ function mergeAsciiDoc (
     doc.source_header_attributes ??= toHash()
     const isRootPage = isRootEntry
     const { component, version, module: module_, relative, origin } = page.src
-    const doctypeOverride = doc.getAttribute('assembly-doctype')
-    if (doctypeOverride) {
-      if (doctypeOverride !== doctype) builder.setDoctype(doctypeOverride)
-      if (doctypeOverride !== 'book') atBookRoot = supportsParts = false
-    }
-    if (isRootPage && doc.hasAttribute('assembly-slug')) builder.slug = doc.getAttribute('assembly-slug')
     let hasAssemblyNavtitleAttr
     if ((hasAssemblyNavtitleAttr = !!doc.getAttribute('assembly-navtitle'))) {
-      navtitleAsciiDoc = doc.getAttribute('assembly-navtitle')
-      navtitlePlain = sanitize((navtitle = doc.$apply_reftext_subs(navtitleAsciiDoc)))
-      if (isRootPage) builder.setDoctitle(navtitle, navtitleAsciiDoc, navtitlePlain)
+      navtitleAsciiDoc = unconvertInlineAsciiDoc(doc.getAttribute('assembly-navtitle'))
+      navtitlePlain = sanitize((navtitle = doc.$sub_attributes(doc.$apply_reftext_subs(navtitleAsciiDoc))))
     }
-    const overviewTitle = doc.getAttribute('assembly-overview-title', 'Overview')
+    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 = `#${pageId}`
@@ -299,6 +317,7 @@ function mergeAsciiDoc (
     const ignoreLines = []
     const buffer = (builder.body ??= [])
     if (buffer.length) buffer.push('')
+    let headerHasBlockAttrs
     if (doc.hasHeader()) {
       for (const entry of processPageHeader(doc, lines, ignoreLines, isRootPage)) {
         if (entry.type === 'author_line') {
@@ -315,8 +334,8 @@ function mergeAsciiDoc (
               (val = doc.getAttribute(name)) &&
               (newVal = rewriteImageAttr(val, contentCatalog, assemblyModel, page.src, assembled.assets)) != null
             ) {
-              if (newVal !== val) entry.lines = [`:${name}: ${newVal}`]
-            } else if (~(val = entry.lines.join('\n').substring(name.length + 3)).indexOf(':')) {
+              if (newVal !== val) entry.value = newVal
+            } else if (~(val = entry.value).indexOf(':')) {
               newVal = val
               if (~newVal.indexOf('image:')) {
                 newVal = rewriteInlineImages(
@@ -343,19 +362,19 @@ function mergeAsciiDoc (
                   { file: relative, lineno: entry.lineno }
                 )
               }
-              if (newVal !== val) entry.lines = `:${entry.name}: ${newVal}`.split('\n')
+              if (newVal !== val) entry.value = newVal
             }
           }
           ;(entry.promote ? builder.header : buffer).push(...entry.lines)
         } else {
-          if (entry.type === 'attrlist') builder.headerHasBlockAttrs = true
+          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)
-    buffer.push(`:page-docname: ${docname}`)
+    buffer.push(`:page-docname: ${pageDocname}`)
     if (component !== builder.currentComponentVersion.name) {
       const thisComponentVersion =
         component === componentVersion.name && version === componentVersion.version
@@ -372,13 +391,22 @@ function mergeAsciiDoc (
     }
     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}`)
+    if (origin) {
+      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}`)
+    } else {
+      buffer.push(':!page-origin-url:')
+      buffer.push(':!page-origin-start-path:')
+      buffer.push(':!page-origin-refname:')
+      buffer.push(':!page-origin-reftype:')
+      buffer.push(':!page-origin-refhash:')
+    }
+    buffer.push(`:page-url: ${page.pub.url}`)
     let heading
-    if (pageStyle != null && isRootPage) {
+    if (isRootPage && pageStyle != null) {
       let htitleAsciiDoc, htitleOverride
       if (pageStyle === 'preface') {
         const hasPrefaceTitleAttr =
@@ -398,7 +426,7 @@ function mergeAsciiDoc (
         }
         if (htitleOverride === '') {
           nextSectionLevel = 2
-          if (builder.headerHasBlockAttrs) {
+          if (headerHasBlockAttrs) {
             htitleAsciiDoc = ''
           } else {
             sectionMergeStrategy = 'discrete'
@@ -410,7 +438,7 @@ function mergeAsciiDoc (
           htitleAsciiDoc = htitleOverride == null ? navtitleAsciiDoc : unconvertInlineAsciiDoc(htitleOverride)
           if (htitleOverride === overviewTitle) overviewTitleAsciiDoc = htitleAsciiDoc // optimization
           if (atBookRoot && hasPrefaceTitleAttr) {
-            if (!builder.headerHasBlockAttrs && (sectionMergeStrategy === 'discrete' || !hasSections)) {
+            if (!headerHasBlockAttrs && (sectionMergeStrategy === 'discrete' || !hasSections)) {
               builder.header.push(`:preface-title: ${htitleAsciiDoc}`)
               htitleAsciiDoc = undefined
             }
@@ -445,7 +473,7 @@ function mergeAsciiDoc (
       heading = { title: navtitleAsciiDoc, hlevel: level-- } // NOTE: level will always come in at 1
       nextSectionLevel = pageStyle === 'part' ? 1 : 2
     } else if (level) {
-      if (atStartOfBody && !pageStyle && builder.matchesDoctitle(navtitlePlain)) {
+      if (atStartOfBody && pageStyle == null && !headerHasBlockAttrs && builder.matchesDoctitle(navtitlePlain)) {
         level--
       } else if ((heading = { title: navtitleAsciiDoc, hlevel: level + 1 }).hlevel > 6) {
         Object.assign(heading, { hlevel: 6, style: `discrete.h${heading.hlevel}` })
@@ -455,14 +483,14 @@ function mergeAsciiDoc (
       const rolesAttr = pageRoles.reduce((str, it) => str + '.' + it, '')
       const notitle = (heading.title ||= '{empty}') === '{empty}'
       // remove conditional if we always want to promote ID of root page to docid
-      if (notitle) {
+      if (atStartOfBody && notitle) {
         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'
+      if ((notitle && pageStyle != null) || !supportsSections) sectionMergeStrategy = 'discrete'
     } else if (atStartOfBody) {
       builder.setDocid(pageId)
     }
@@ -799,6 +827,14 @@ function processPageHeader (doc, lines, ignoreLines, isRootPage) {
         } else {
           if (line.endsWith(' \\')) open = ':'
           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
@@ -824,9 +860,9 @@ function processPageHeader (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, '')
@@ -839,8 +875,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) {

package/lib/produce-assembly-files.js

@@ -39,7 +39,7 @@ function produceAssemblyFiles (
     const { attributes: assemblyAttributes, logger, navigation, rootLevel } = assemblyModel
     if (!navigation) return accum
     const contextualLogger = logger ? { warn: logger.warn.bind(logger, configMdc) } : undefined
-    const { name: componentName, version, title } = componentVersion
+    const { name: componentName, version } = componentVersion
     const asciidocConfig = getAsciiDocConfigWithAsciidoctorReducerExtension(componentVersion, reducerExtension)
     let sourceHighlighter
     if ('source-highlighter' in assemblyAttributes) {
@@ -83,10 +83,9 @@ function produceAssemblyFiles (
     } else if (!(assemblyModel.filetype === 'pdf' && assemblyModel.linkReferenceStyle === 'relative')) {
       assemblyModel.linkReferenceStyle = 'absolute'
     }
-    const outlineRoot = { content: title }
-    const startPage = resolveStartPage(contentCatalog, componentVersion, assemblyModel.insertStartPage, outlineRoot)
+    const [startPage, outlineRoot] = resolveStartPage(contentCatalog, componentVersion, assemblyModel.insertStartPage)
     const mutableAttributes = identifyMutableAttributes(loadAsciiDoc, contentCatalog, startPage, mergedAsciiDocConfig)
-    prepareOutlines(navigation, outlineRoot, rootLevel).reduce((any, outline) => {
+    prepareOutlines(navigation, outlineRoot, rootLevel).forEach((outline) => {
       const assemblyFile = produceAssemblyFile(
         loadAsciiDoc,
         contentCatalog,
@@ -97,15 +96,15 @@ function produceAssemblyFiles (
         mutableAttributes,
         assemblyModel
       )
-      if (!assemblyFile) return any
+      if (!assemblyFile) return
       // NOTE restore source highlighter for conversion if defined in Assembler config
       if (sourceHighlighter !== undefined) {
         assemblyFile.asciidoc.attributes['source-highlighter'] = sourceHighlighter
       } else if (assemblyModel.filetype !== 'html') {
         delete assemblyFile.asciidoc.attributes['source-highlighter']
       }
-      return !!accum.push(assemblyFile)
-    }, false)
+      accum.push(assemblyFile)
+    })
     return accum
   }, [])
 }
@@ -129,53 +128,67 @@ function includedInNav (items, url) {
   return items.find((it) => it.url === url || includedInNav(it.items || [], url))
 }
 
-function resolveStartPage (contentCatalog, componentVersion, insertStartPage, outlineRoot) {
-  const { name: componentName, version } = componentVersion
-  const startPage =
+function resolveStartPage (contentCatalog, componentVersion, insertStartPage) {
+  const { name: componentName, version, title } = componentVersion
+  const outlineRoot = { content: title }
+  let startPage =
     'startPage' in componentVersion
       ? componentVersion.startPage
       : contentCatalog.resolvePage('index.adoc', { component: componentName, version })
   if (startPage && startPage.src.component === componentName && startPage.src.version === version) {
-    if (insertStartPage) {
-      const navtitle = startPage.asciidoc?.navtitle || outlineRoot.content
-      Object.assign(outlineRoot, { navtitle, url: startPage.pub.url, urlType: 'internal', roles: ['page'] })
-    }
-    return startPage
+    const navtitle = startPage.asciidoc?.navtitle ?? outlineRoot.content
+    Object.defineProperty(outlineRoot, 'startPageEntry', {
+      value: { navtitle, url: startPage.pub.url, urlType: 'internal', roles: ['page'] },
+    })
+    if (insertStartPage) Object.defineProperty(outlineRoot.startPageEntry, 'insert', { value: true })
+  } else {
+    startPage = contentCatalog.createFile({
+      src: {
+        component: componentName,
+        version,
+        componentVersion,
+        module: 'ROOT',
+        family: 'page',
+        relative: 'index.adoc',
+        origin: componentVersion.origins?.values().next().value,
+      },
+    })
   }
-  return contentCatalog.createFile({
-    src: {
-      component: componentName,
-      version,
-      componentVersion,
-      module: 'ROOT',
-      family: 'page',
-      relative: 'index.adoc',
-      origin: componentVersion.origins?.values().next().value,
-    },
-  })
+  return [startPage, outlineRoot]
 }
 
 function prepareOutlines (navigation, rootEntry, rootLevel) {
-  const singleEntry = navigation.length === 1
+  const startPageEntry = rootEntry.startPageEntry
+  const singleListWithTitle = navigation.length === 1 && 'content' in navigation[0] ? navigation[0] : undefined
+  if (singleListWithTitle) {
+    const { content, url, urlType } = singleListWithTitle
+    if (urlType === 'internal') {
+      if (startPageEntry && url === startPageEntry.url) {
+        if (!startPageEntry.insert) Object.defineProperty(startPageEntry, 'insert', { value: true })
+        //if (!(content === startPageEntry.content || content === startPageEntry.navtitle)) {
+        //  startPageEntry.content = content
+        //}
+        startPageEntry.roles = singleListWithTitle.roles
+        navigation = [{ items: singleListWithTitle.items }]
+      }
+    } else if (content === rootEntry.content) {
+      delete Object.assign(rootEntry, singleListWithTitle).items
+      navigation = [{ items: singleListWithTitle.items }]
+    }
+  }
   const items = navigation.reduce((accum, it) => {
-    if (!it.content || (singleEntry && it.url ? it.url === rootEntry.url : it.content === rootEntry.content)) {
-      it.items && accum.push(...it.items)
-    } else {
+    if ('content' in it) {
       accum.push(it)
+    } else if (it.items) {
+      accum.push(...it.items)
     }
     return accum
   }, [])
-  if (rootLevel === 0) {
-    if (rootEntry.url && includedInNav(items, rootEntry.url)) {
-      for (const p of ['roles', 'url', 'urlType']) delete rootEntry[p]
-    }
-    return [Object.assign(rootEntry, { index: true, items })]
-  }
-  if (rootEntry.url && !includedInNav(items, rootEntry.url)) {
-    rootEntry.content = singleEntry && rootEntry.url === navigation[0].url ? navigation[0].content : rootEntry.navtitle
-    items.unshift(rootEntry)
+  if (startPageEntry?.insert && !includedInNav(items, startPageEntry.url)) {
+    Object.assign(rootEntry, startPageEntry)
+    if (rootLevel !== 0) items.unshift(Object.assign(rootEntry, { content: rootEntry.navtitle }))
   }
-  return items
+  return rootLevel === 0 ? [Object.assign(rootEntry, { items })] : items
 }
 
 function extractUrlPath (url) {

package/lib/util/unconvert-inline-asciidoc.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const ATTRIBUTE_REFERENCE_RX = /\{[a-z0-9_][a-z0-9_-]*\}/g
+const ATTRIBUTE_REFERENCE_RX = /\{[A-Za-z0-9_][A-Za-z0-9_-]*\}/g
 const STRICT_WORD_CHAR_RX = /[\p{L}\d_]/u
 const WORD_CHAR_RX = /[\p{L}\d_;}:<>]/u
 const XML_SPECIAL_CHARS = { '&lt;': '<', '&gt;': '>', '&amp;': '&' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/assembler",
-  "version": "1.0.0-rc.10",
+  "version": "1.0.0-rc.12",
   "description": "A JavaScript library that merges AsciiDoc content from multiple pages in an Antora site into assembly files and delegates to an exporter to convert those files to another format, such as PDF.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
@@ -39,12 +39,12 @@
     "@antora/expand-path-helper": "~3.0",
     "@antora/run-command-helper": "~1.1",
     "@asciidoctor/reducer": "~1.1",
-    "js-yaml": "~5.3"
+    "js-yaml": "~5.4"
   },
   "devDependencies": {
-    "@antora/asciidoc-loader": "3.2.0-rc.3",
-    "@antora/navigation-builder": "3.2.0-rc.3",
-    "@antora/site-publisher": "3.2.0-rc.3"
+    "@antora/asciidoc-loader": "~3.2",
+    "@antora/navigation-builder": "~3.2",
+    "@antora/site-publisher": "~3.2"
   },
   "engines": {
     "node": ">=20.0.0"