@antora/pdf-extension 1.0.0-alpha.9 → 1.0.0-beta.1

package/README.md

@@ -1,12 +1,12 @@
 # Antora PDF Extension
 
-The Antora PDF Extension is the official extension for producing PDFs of an Antora site.
-Specifically, it generates and publishes PDFs of aggregate pages in the site.
+The Antora PDF extension is an Antora extension and exporter for Assembler.
+It configures and invokes Assembler and it provides the converter function and metadata that Assembler uses to export content to the PDF format.
+This extension is the official extension for exporting content in an Antora site to PDF.
 
-This extension is based on Antora Assembler.
-It calls Assembler to construct aggregate AsciiDoc documents from pages based on the navigation tree per component version.
-It then iterates over those aggregate documents and converts them to PDF using Asciidoctor PDF or the specified command.
-Finally, it pushes those PDFs into the site catalog so they are published as attachments alongside the other files in the site.
+This extension first delegates to Assembler, passing it the converter metadata, to construct assembly files from pages per component version using the navigation as a model.
+Assembler then iterates over those assembly files and, using the converter provided by this extension, converts them to PDF using Asciidoctor PDF (or the specified command).
+Finally, Assembler adds those PDFs to the content catalog as exports, which Antora then publishes alongside the other files in the site.
 
 ## Usage
 

package/lib/converter.js

@@ -0,0 +1,29 @@
+'use strict'
+
+const fsp = require('node:fs/promises')
+const ospath = require('node:path')
+
+const DEFAULT_COMMAND = 'asciidoctor-pdf'
+
+async function convert (runCommand, file, convertAttributes, buildConfig) {
+  const { cwd = process.cwd(), command = await getDefaultCommand(cwd) } = buildConfig
+  const args = convertAttributes.toArgs('-a', command).concat('-o', convertAttributes.outfile, '-')
+  await runCommand(command, args, { parse: true, cwd, stdin: file.contents, stdout: 'print', stderr: 'print' })
+}
+
+function getDefaultCommand (cwd) {
+  return fsp.access(ospath.join(cwd, 'Gemfile.lock')).then(
+    () => `bundle exec ${DEFAULT_COMMAND}`,
+    () => DEFAULT_COMMAND
+  )
+}
+
+module.exports = {
+  bind (thisArg, runCommand) {
+    return Object.assign({}, this, { convert: convert.bind(thisArg, runCommand) })
+  },
+  convert,
+  backend: 'pdf',
+  extname: '.pdf',
+  mediaType: 'application/pdf',
+}

package/lib/index.js

@@ -1,19 +1,15 @@
 'use strict'
 
-const convertDocumentToPdf = require('./convert-document-to-pdf')
+const converter = require('./converter')
+const runCommand = require('@antora/run-command-helper')
 
-module.exports.register = function ({ config: { configFile: configSource } }) {
-  this.once('beforeProcess', ({ siteAsciiDocConfig }) => {
-    siteAsciiDocConfig.keepSource = true
-  })
-  this.once('navigationBuilt', ({ playbook, contentCatalog, siteCatalog }) => {
-    const { assembleContent } = (() => {
-      try {
-        return this.require('@antora/assembler') // when installed with Antora
-      } catch {
-        return require('@antora/assembler') // when installed separate from Antora, perhaps in project
-      }
-    })()
-    return assembleContent.call(this, playbook, contentCatalog, convertDocumentToPdf, { configSource, siteCatalog })
-  })
+module.exports.register = function ({ config }, providers) {
+  requireAssembler(this).configure(this, converter.bind(this, runCommand), config, providers)
+}
+
+function requireAssembler (context, packageName = '@antora/assembler') {
+  try {
+    return context.require(packageName) // when installed with Antora
+  } catch {}
+  return require(packageName) // when installed separate from Antora, perhaps in project
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antora/pdf-extension",
-  "version": "1.0.0-alpha.9",
-  "description": "An Antora extension that assembles content pages into PDF files by version and publishes them with the site.",
+  "version": "1.0.0-beta.1",
+  "description": "An Antora extension that uses Assembler to merge pages into assembly files, export them to the PDF format, and publishe them with the site.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
   "contributors": [
@@ -9,24 +9,31 @@
     "Sarah White <sarah@opendevise.com>"
   ],
   "homepage": "https://antora.org",
-  "repository": "gitlab:antora/antora-assembler",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/antora/antora-assembler.git",
+    "directory": "packages/pdf-extension"
+  },
   "bugs": {
     "url": "https://gitlab.com/antora/antora-assembler/issues"
   },
   "scripts": {
-    "test": "_mocha test",
+    "test": "node --test test/*-test.js",
     "prepublishOnly": "npx -y downdoc --prepublish",
     "postpublish": "npx -y downdoc --postpublish"
   },
   "main": "lib/index.js",
   "exports": {
-    ".": "./lib/index.js"
+    ".": "./lib/index.js",
+    "./converter": "./lib/converter.js",
+    "./package.json": "./package.json"
   },
   "imports": {
-    "#convert-document-to-pdf": "./lib/convert-document-to-pdf.js"
+    "#package": "./package.json"
   },
   "dependencies": {
-    "@antora/assembler": "1.0.0-alpha.9"
+    "@antora/assembler": "1.0.0-beta.1",
+    "@antora/run-command-helper": "~1.0"
   },
   "engines": {
     "node": ">=16.0.0"
@@ -42,8 +49,5 @@
     "pdf",
     "generator",
     "documentation"
-  ],
-  "publishConfig": {
-    "access": "public"
-  }
+  ]
 }

package/lib/convert-document-to-pdf.js

@@ -1,47 +0,0 @@
-'use strict'
-
-const fsp = require('node:fs/promises')
-const ospath = require('node:path')
-
-// Q: how can we simplify this to avoid redundant code?
-// Q: rename to convertDocumentToPDF?
-async function convertDocumentToPdf (doc, buildConfig, runCommand) {
-  const {
-    asciidoc: { attributes: baseAttributes } = { attributes: {} },
-    contents: input,
-    src: { component, version, basename, extname = doc.extname },
-  } = doc
-  const { cwd = process.cwd(), dir = cwd } = buildConfig
-  const command = buildConfig.command ?? (await scopeDefaultCommand(cwd))
-  const docfile = `${version}@${component}::pdf$${basename}`
-  const docname = basename.slice(0, basename.length - extname.length)
-  const convertAttributes = Object.assign({}, baseAttributes, {
-    docfile,
-    docfilesuffix: extname,
-    'docname@': docname,
-    imagesdir: dir,
-  })
-  Object.assign(doc, { contents: null, extname: '.pdf', mediaType: 'application/pdf' })
-  const argv = Object.entries(convertAttributes).reduce(
-    (accum, [name, val]) =>
-      accum.push('-a', val ? `${name}=${val}` : val === '' ? name : `!${name}${val === false ? '=@' : ''}`) && accum,
-    []
-  )
-  const output = ospath.join(dir, doc.path)
-  // Q: should mkdirs be the default behavior?
-  if (buildConfig.mkdirs) await fsp.mkdir(ospath.dirname(output), { recursive: true, force: true })
-  argv.push('-o', output)
-  // Q: should runCommand accept outputFlag and automatically append to argv?
-  return runCommand(command, argv, { cwd, input, output }).then((contents) =>
-    Object.assign(doc, { contents, out: { path: doc.path } })
-  )
-}
-
-function scopeDefaultCommand (cwd, baseCommand = 'asciidoctor-pdf') {
-  return fsp.stat(ospath.join(cwd, 'Gemfile.lock')).then(
-    () => `bundle exec ${baseCommand}`,
-    () => baseCommand
-  )
-}
-
-module.exports = convertDocumentToPdf