@baiyibai-antora/adf-extension 1.0.0-beta.1

package/README.adoc

@@ -0,0 +1,5 @@
+= @baiyibai-antora/adf-extension
+
+Antora extension that converts every publishable page of an Antora site to Confluence-native ADF JSON during a normal site build, plus a `manifest.json` publish contract for `@baiyibai-antora/confluence-publisher`.
+
+Full documentation lives in the repository https://gitlab.com/baiyibai-antora/confluora/-/blob/main/README.adoc[README].

package/lib/convert-pages.js

@@ -0,0 +1,303 @@
+'use strict'
+
+const { createHash } = require('node:crypto')
+const fsp = require('node:fs/promises')
+const ospath = require('node:path')
+const { posix: path } = require('node:path')
+const { convert } = require('@baiyibai-antora/asciidoc-adf-converter')
+const extractNav = require('./nav')
+
+const pageKey = (src) => [src.component, src.version, src.module, src.relative].join(':')
+const md5 = (buf) => createHash('md5').update(buf).digest('hex')
+const sha1 = (str) => createHash('sha1').update(str).digest('hex')
+
+// Confluence page titles are plain text; doctitles and nav link texts can
+// carry inline markup, entities, and (when metadata was extracted without
+// extensions loaded) an unconsumed leading macro escape.
+const ENTITIES = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'", '&nbsp;': ' ', '&hellip;': '…' }
+const plainText = (html) =>
+  html &&
+  html
+    .replace(/<[^>]+>/g, '')
+    .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_, num) => String.fromCodePoint(Number(num)))
+    .replace(/&[a-z]+;/gi, (ref) => ENTITIES[ref] || ref)
+    .replace(/[​-‍]/g, '') // zero-width chars from AsciiDoc word joiners
+    .replace(/^\\(?=[a-z])/i, '')
+    .trim()
+
+// HTML-pipeline extensions (e.g. list-of-site) leave placeholder divs in the
+// AsciiDoc-derived pass blocks and inject the real content into the page's
+// converted HTML at documentsConverted — which has already run by the time we
+// re-load the source. Splice the generated markup back into the placeholders.
+const PLACEHOLDER_RX = /<div\s+class="list-of-site-placeholder[^"]*"\s+data-element="([^"]+)">\s*<\/div>/g
+function createPassTransform (page) {
+  const html = page.contents && page.contents.toString()
+  if (!html || !html.includes('list-of')) return null
+  const used = {}
+  return (passHtml) =>
+    passHtml.replace(PLACEHOLDER_RX, (match, element) => {
+      const generated =
+        html.match(new RegExp(`<ul class="list-of-${element}[^"]*">[\\s\\S]*?</ul>`, 'g')) || []
+      const idx = (used[element] = (used[element] ?? -1) + 1)
+      return generated[idx] || ''
+    })
+}
+
+// Never surface a raw source path as a page title: fall back to the nav link
+// text, then to a titleized filename stem.
+function pageTitle (page, key, navTitles) {
+  const doctitle = plainText(page.title)
+  if (doctitle) return doctitle
+  const navTitle = plainText(navTitles.get(key))
+  if (navTitle) return navTitle
+  const stem = page.src.relative.replace(/\.adoc$/, '').split('/').pop().replace(/[-_]+/g, ' ')
+  return stem.charAt(0).toUpperCase() + stem.slice(1)
+}
+
+module.exports = async function convertPages ({
+  playbook,
+  contentCatalog,
+  navigationCatalog,
+  loadAsciiDoc,
+  config,
+  logger,
+}) {
+  const outputDir = ospath.resolve(playbook.dir || '.', config.outputDir || path.join('build', 'adf'))
+  const included = buildVersionFilter(contentCatalog, config)
+
+  const asciidocConfigs = new Map()
+  for (const component of contentCatalog.getComponents()) {
+    for (const { version, asciidoc } of component.versions) {
+      asciidocConfigs.set(`${component.name}@${version}`, asciidoc)
+    }
+  }
+
+  const pages = contentCatalog.getPages(
+    (page) => page.out && page.src.contents && included(page.src, pageKey(page.src))
+  )
+  const urlIndex = new Map(pages.map((page) => [page.pub.url, page]))
+  const { nav, parents, order, navTitles } = extractNav(contentCatalog, navigationCatalog, urlIndex, pageKey, included)
+
+  // Nav parity: pages absent from the Antora navigation are orphans — they
+  // never appear in the site's sidebar, so by default they don't publish
+  // either (links to them fall back to the static site). Component start
+  // pages always publish; set orphans: include to publish everything.
+  const startKeys = new Set(nav.map((entry) => entry.startKey).filter(Boolean))
+  let publishable = pages
+  if (config.orphans !== 'include') {
+    publishable = pages.filter((page) => {
+      const key = pageKey(page.src)
+      if (order.has(key) || startKeys.has(key)) return true
+      logger.info(`${key}: not in the Antora navigation; skipping (set orphans: include to publish)`)
+      return false
+    })
+  }
+
+  const writtenAttachments = new Map() // output-relative path -> contents
+  const manifestPages = []
+
+  for (const page of publishable) {
+    const key = pageKey(page.src)
+    const asciidocConfig = asciidocConfigs.get(`${page.src.component}@${page.src.version}`) || {}
+    const doc = loadAsciiDoc(
+      {
+        contents: page.src.contents,
+        src: page.src,
+        pub: page.pub,
+        out: page.out,
+        path: page.path,
+        dirname: ospath.dirname(page.path),
+      },
+      contentCatalog,
+      // Root-relative refs map directly onto the pub.url page index.
+      Object.assign({}, asciidocConfig, { relativizeResourceRefs: false })
+    )
+
+    const attachments = []
+    const attachmentsBySource = new Map()
+    const xrefs = []
+
+    const result = convert(doc, {
+      transformPassContent: createPassTransform(page),
+      resolveImage: (target) => {
+        if (/^(https?|data):/.test(target)) return { url: target }
+        const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
+        if (!image || !image.contents) return null
+        const sourceKey = pageKey(image.src)
+        let entry = attachmentsBySource.get(sourceKey)
+        if (!entry) {
+          const hash = md5(image.contents)
+          const relPath = path.join(
+            'attachments',
+            image.src.component,
+            image.src.version,
+            image.src.module,
+            image.src.relative
+          )
+          writtenAttachments.set(relPath, image.contents)
+          entry = {
+            placeholderId: hash,
+            path: relPath,
+            filename: path.basename(image.src.relative),
+            md5: hash,
+          }
+          attachmentsBySource.set(sourceKey, entry)
+          attachments.push(entry)
+        }
+        return { id: entry.placeholderId, collection: '' }
+      },
+      resolveXref: (href, attribs = {}) => {
+        if (!href) return { href }
+        // Extension-generated HTML (e.g. list-of-site) links relative to the
+        // page; normalize to root-relative so the publisher can map it.
+        let resolved = href
+        if (href.charAt(0) !== '/' && !/^[a-z][a-z0-9+.-]*:/i.test(href) && href.charAt(0) !== '#') {
+          resolved = path.resolve(path.dirname(page.pub.url), href)
+        }
+        if (resolved.charAt(0) === '/') {
+          const [urlPath, fragment] = resolved.split('#')
+          const targetPage = urlIndex.get(urlPath)
+          const xref = { href: resolved, targetKey: targetPage ? pageKey(targetPage.src) : null }
+          if (fragment) xref.fragment = fragment
+          if (!targetPage && /(^| )xref( |$)/.test(attribs.class || '')) {
+            logger.warn(`${key}: xref "${resolved}" does not resolve to a published page`)
+          }
+          xrefs.push(xref)
+          return { href: resolved }
+        }
+        return { href }
+      },
+    })
+
+    for (const warning of result.warnings) logger.warn(`${key}: ${warning}`)
+
+    const adfJson = JSON.stringify(result.adf, null, 2) + '\n'
+    const adfPath = path.join(
+      'pages',
+      page.src.component,
+      page.src.version,
+      page.src.module,
+      page.src.relative.replace(/\.adoc$/, '.adf.json')
+    )
+    const outFile = ospath.join(outputDir, ...adfPath.split('/'))
+    await fsp.mkdir(ospath.dirname(outFile), { recursive: true })
+    await fsp.writeFile(outFile, adfJson)
+
+    manifestPages.push({
+      key,
+      title: pageTitle(page, key, navTitles),
+      adfPath,
+      url: page.pub.url,
+      // The page's source in its git repository, as a VIEW url — Antora's
+      // editUrl points at the edit form, which forces a forge login; the
+      // blob/view page is public and still offers Edit to those who can.
+      // Local-worktree builds yield file:// urls — never publishable.
+      sourceUrl:
+        page.src.editUrl && /^https?:/.test(page.src.editUrl)
+          ? page.src.editUrl.replace(/\/edit\//, '/blob/')
+          : null,
+      navOrder: order.has(key) ? order.get(key) : null,
+      parentKey: parents.get(key) || null,
+      xrefs,
+      attachments,
+      anchors: result.anchors,
+      contentHash: sha1(adfJson),
+    })
+  }
+
+  for (const [relPath, contents] of writtenAttachments) {
+    const outFile = ospath.join(outputDir, ...relPath.split('/'))
+    await fsp.mkdir(ospath.dirname(outFile), { recursive: true })
+    await fsp.writeFile(outFile, contents)
+  }
+
+  // Stable page order: nav pages first (nav order), then the rest by key.
+  manifestPages.sort((a, b) => {
+    if (a.navOrder != null && b.navOrder != null) return a.navOrder - b.navOrder
+    if (a.navOrder != null) return -1
+    if (b.navOrder != null) return 1
+    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0
+  })
+
+  logger.info(`wrote ${manifestPages.length} ADF page(s) and ${writtenAttachments.size} attachment(s) to ${outputDir}`)
+  // The manifest itself is written by finalizeManifest (on beforePublish), so
+  // assembler-produced exports (family "export") are collected regardless of
+  // extension registration order.
+  return { outputDir, manifestPages, nav, included }
+}
+
+// Component/version scoping: `components` limits to the listed component
+// names; `versions: latest` keeps only each component's latest version;
+// `exclude` is a list of globs matched against component names and full page
+// keys (component:version:module:relative).
+function buildVersionFilter (contentCatalog, config) {
+  const components = Array.isArray(config.components) && config.components.length ? config.components : null
+  const latestOnly = config.versions === 'latest'
+  const latest = new Map(contentCatalog.getComponents().map((c) => [c.name, c.latest && c.latest.version]))
+  const excludes = (Array.isArray(config.exclude) ? config.exclude : []).map(globToRx)
+  return (src, key) => {
+    if (components && !components.includes(src.component)) return false
+    if (latestOnly && latest.get(src.component) !== src.version) return false
+    for (const rx of excludes) {
+      if (rx.test(src.component)) return false
+      if (key && rx.test(key)) return false
+    }
+    return true
+  }
+}
+
+function globToRx (pattern) {
+  const escaped = String(pattern).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')
+  return new RegExp(`^${escaped}$`)
+}
+
+/**
+ * beforePublish hook: collect assembler exports (family "export", e.g. PDFs)
+ * scoped to the included component versions, copy their bytes, and write the
+ * final manifest.json.
+ */
+async function finalizeManifest ({ playbook, contentCatalog, state, logger }) {
+  const { outputDir, manifestPages, nav, included } = state
+  const exports_ = []
+  for (const file of contentCatalog.getFiles()) {
+    if (!file.src || file.src.family !== 'export' || !file.out || !file.contents) continue
+    if (!included(file.src)) continue
+    // Assembler exports carry their bytes as a lazy stream, not a Buffer.
+    const contents = Buffer.isBuffer(file.contents) ? file.contents : await bufferStream(file.contents)
+    // A generic "index.pdf" makes a poor download; qualify it.
+    let filename = path.basename(file.out.path)
+    if (filename.startsWith('index.')) filename = `${file.src.component}-${file.src.version}${filename.slice(5)}`
+    const relPath = path.join('exports', file.src.component, file.src.version, filename)
+    const outFile = ospath.join(outputDir, ...relPath.split('/'))
+    await fsp.mkdir(ospath.dirname(outFile), { recursive: true })
+    await fsp.writeFile(outFile, contents)
+    exports_.push({
+      component: file.src.component,
+      version: file.src.version,
+      filename,
+      path: relPath,
+      md5: md5(contents),
+    })
+    logger.info(`collected export ${filename} (${file.src.component}@${file.src.version})`)
+  }
+
+  const manifest = {
+    version: 1,
+    site: { title: playbook.site.title || null, url: playbook.site.url || null },
+    pages: manifestPages,
+    nav,
+    exports: exports_,
+  }
+  await fsp.writeFile(ospath.join(outputDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n')
+  logger.info(`wrote manifest: ${manifestPages.length} page(s), ${exports_.length} export(s)`)
+  return manifest
+}
+
+async function bufferStream (stream) {
+  const chunks = []
+  for await (const chunk of stream) chunks.push(chunk)
+  return Buffer.concat(chunks)
+}
+
+module.exports.finalizeManifest = finalizeManifest

package/lib/index.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const convertPages = require('./convert-pages')
+const { finalizeManifest } = require('./convert-pages')
+const loadConfig = require('./load-config')
+
+module.exports.register = function ({ config = {} }) {
+  const logger = this.getLogger('adf-extension')
+  let state
+
+  // The AsciiDoc source of each page must survive HTML conversion so it can
+  // be re-loaded and walked for ADF output.
+  this.once('beforeProcess', ({ siteAsciiDocConfig }) => {
+    siteAsciiDocConfig.keepSource = true
+  })
+
+  this.once('navigationBuilt', async ({ playbook, contentCatalog, navigationCatalog }) => {
+    const loadAsciiDoc = this.require('@antora/asciidoc-loader')
+    const resolvedConfig = loadConfig(playbook, config, logger)
+    state = await convertPages({
+      playbook,
+      contentCatalog,
+      navigationCatalog,
+      loadAsciiDoc,
+      config: resolvedConfig,
+      logger,
+    })
+  })
+
+  // Deferred to beforePublish so assembler exports (PDFs etc., family
+  // "export") exist in the catalog no matter the extension order.
+  this.once('beforePublish', async ({ playbook, contentCatalog }) => {
+    if (state) await finalizeManifest({ playbook, contentCatalog, state, logger })
+  })
+}

package/lib/load-config.js

@@ -0,0 +1,45 @@
+'use strict'
+
+const fs = require('node:fs')
+const ospath = require('node:path')
+const yaml = require('js-yaml')
+
+// Confluence-specific site configuration lives in a YAML file next to the
+// playbook (default: confluence.yml, override with the config_file key), so
+// publishing concerns stay out of the Antora playbook proper:
+//
+//   nav_exclude:        # not published to Confluence (globs vs component
+//     - my-presentation #   names / page keys); the sources stay in the
+//   versions: latest    #   Antora catalog, so includes and xrefs resolve —
+//   components: [docs]  #   links to nav-excluded pages fall back to the
+//   output_dir: ./build/adf  # static site url. `exclude` is an alias.
+//
+// Keys given directly on the extension entry in the playbook win.
+
+function loadConfig (playbook, config, logger) {
+  const filename = config.configFile || 'confluence.yml'
+  const configPath = ospath.resolve(playbook.dir || '.', filename)
+  if (!fs.existsSync(configPath)) {
+    if (config.configFile) logger.warn(`confluence config file not found: ${configPath}`)
+    return config
+  }
+  let fileConfig
+  try {
+    fileConfig = yaml.load(fs.readFileSync(configPath, 'utf8')) || {}
+  } catch (err) {
+    logger.warn(`could not parse ${configPath}: ${err.message}`)
+    return config
+  }
+  const normalized = {}
+  if (fileConfig.exclude || fileConfig.nav_exclude) {
+    normalized.exclude = [...(fileConfig.exclude || []), ...(fileConfig.nav_exclude || [])]
+  }
+  if (fileConfig.versions) normalized.versions = fileConfig.versions
+  if (fileConfig.orphans) normalized.orphans = fileConfig.orphans
+  if (fileConfig.components) normalized.components = fileConfig.components
+  if (fileConfig.output_dir) normalized.outputDir = fileConfig.output_dir
+  logger.info(`loaded confluence config from ${configPath}`)
+  return { ...normalized, ...config }
+}
+
+module.exports = loadConfig

package/lib/nav.js

@@ -0,0 +1,54 @@
+'use strict'
+
+// Extracts the navigation tree per component version, resolving internal nav
+// URLs back to page keys. Returns the manifest nav plus page parent/order
+// maps derived from a depth-first walk.
+
+module.exports = function extractNav (contentCatalog, navigationCatalog, urlIndex, pageKey, included = () => true) {
+  const nav = []
+  const parents = new Map()
+  const order = new Map()
+  const navTitles = new Map()
+  let counter = 0
+
+  const visit = (item, parentKey) => {
+    let key = null
+    if (item.urlType === 'internal' && item.url) {
+      const page = urlIndex.get(item.url.split('#')[0])
+      if (page) {
+        key = pageKey(page.src)
+        if (!parents.has(key)) {
+          parents.set(key, parentKey)
+          order.set(key, counter++)
+          if (item.content) navTitles.set(key, item.content)
+        }
+      }
+    }
+    const entry = { title: item.content || null, key }
+    const children = (item.items || []).map((child) => visit(child, key || parentKey))
+    if (children.length) entry.children = children
+    return entry
+  }
+
+  for (const component of contentCatalog.getComponents()) {
+    for (const { version, displayVersion, title, url } of component.versions) {
+      if (!included({ component: component.name, version })) continue
+      const menus = navigationCatalog.getNavigation(component.name, version) || []
+      const entries = []
+      for (const menu of menus) {
+        const rootEntry = menu.url || menu.content ? visit(menu, null) : null
+        if (rootEntry) {
+          entries.push(rootEntry)
+        } else {
+          for (const item of menu.items || []) entries.push(visit(item, null))
+        }
+      }
+      // The component version's start page anchors its subtree in Confluence.
+      const startPage = url && urlIndex.get(url.split('#')[0])
+      const startKey = startPage ? pageKey(startPage.src) : null
+      nav.push({ component: component.name, version, displayVersion, title, startKey, entries })
+    }
+  }
+
+  return { nav, parents, order, navTitles }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@baiyibai-antora/adf-extension",
+  "version": "1.0.0-beta.1",
+  "description": "Antora extension that emits Confluence ADF JSON and a publish manifest for every page during a site build",
+  "license": "MIT",
+  "author": "baiyibai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/baiyibai-antora/confluora.git",
+    "directory": "packages/adf-extension"
+  },
+  "type": "commonjs",
+  "main": "lib/index.js",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "test": "node --test test/*-test.js"
+  },
+  "dependencies": {
+    "@baiyibai-antora/asciidoc-adf-converter": "^1.0.0-beta.1",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "antora": "^3.1.10"
+  },
+  "keywords": [
+    "confluora",
+    "antora",
+    "antora-extension",
+    "adf",
+    "confluence"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://gitlab.com/baiyibai-antora/confluora",
+  "bugs": "https://gitlab.com/baiyibai-antora/confluora/-/issues"
+}