@antora/pdf-extension 1.0.0-alpha.10 → 1.0.0-alpha.12

package/README.md

@@ -1,12 +1,13 @@
 # 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 exporter extension for Assembler that assembles and converts content to the PDF format using Asciidoctor PDF.
+The Antora PDF 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.
+It provides the converter function and metadata that Assembler uses to export content.
+Assembler constructs assembly AsciiDoc documents from pages per component version using the navigation as a model.
+Using the converter provided by this extension, it then iterates over those assembly documents and converts them to PDF using Asciidoctor PDF (or the specified command).
+Finally, it 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,6 +1,6 @@
 {
   "name": "@antora/pdf-extension",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.12",
   "description": "An Antora extension that assembles content pages into PDF files by version and publishes them with the site.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
@@ -9,7 +9,11 @@
     "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"
   },
@@ -20,14 +24,16 @@
   },
   "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",
-    "#run-command": "@antora/run-command-helper"
+    "#package": "./package.json"
   },
   "dependencies": {
-    "@antora/assembler": "1.0.0-alpha.10"
+    "@antora/assembler": "1.0.0-alpha.12",
+    "@antora/run-command-helper": "~1.0"
   },
   "engines": {
     "node": ">=16.0.0"
@@ -43,8 +49,5 @@
     "pdf",
     "generator",
     "documentation"
-  ],
-  "publishConfig": {
-    "access": "public"
-  }
+  ]
 }

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

@@ -1,55 +0,0 @@
-'use strict'
-
-const fs = require('node:fs')
-const { promises: fsp } = fs
-const LazyReadable = require('./util/lazy-readable')
-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: stdin,
-    src: { component, version, basename, extname = doc.extname },
-  } = doc
-  const { cwd = process.cwd(), dir = cwd } = buildConfig
-  const command = buildConfig.command ?? (await scopeDefaultCommand(cwd))
-  const padCharRef = process.platform === 'win32' && command.startsWith('bundle exec ')
-  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 extraArgs = Object.entries(convertAttributes).reduce((accum, [name, val]) => {
-    if (val) {
-      val = `${name}=${padCharRef && val.charAt() === '&' ? ' ' : ''}${val}`
-    } else if (val === '') {
-      val = name
-    } else {
-      val = `!${name}${val === false ? '=@' : ''}`
-    }
-    accum.push('-a', val)
-    return accum
-  }, [])
-  const outputPath = ospath.join(dir, doc.path)
-  // Q: should mkdirs be the default behavior?
-  if (buildConfig.mkdirs) await fsp.mkdir(ospath.dirname(outputPath), { recursive: true, force: true })
-  extraArgs.push('-o', outputPath, '-')
-  return runCommand(command, extraArgs, { parse: true, cwd, stdin, stdout: 'print', stderr: 'print' }).then(() =>
-    Object.assign(doc, { contents: new LazyReadable(() => fs.createReadStream(outputPath)), out: { path: doc.path } })
-  )
-}
-
-function scopeDefaultCommand (cwd, baseCommand = 'asciidoctor-pdf') {
-  return fsp.access(ospath.join(cwd, 'Gemfile.lock')).then(
-    () => `bundle exec ${baseCommand}`,
-    () => baseCommand
-  )
-}
-
-module.exports = convertDocumentToPdf

package/lib/util/lazy-readable.js

@@ -1,18 +0,0 @@
-'use strict'
-
-const { PassThrough } = require('node:stream')
-
-// adapted from https://github.com/jpommerening/node-lazystream/blob/master/lib/lazystream.js | license: MIT
-class LazyReadable extends PassThrough {
-  constructor (fn, options) {
-    super(options)
-    this._read = function () {
-      delete this._read // restores original method
-      fn.call(this, options).on('error', this.emit.bind(this, 'error')).pipe(this)
-      return this._read.apply(this, arguments)
-    }
-    this.emit('readable')
-  }
-}
-
-module.exports = LazyReadable