Custom Exporter Extension

With relatively little effort, you can create your own exporter extension for Assembler. That’s because Assembler exposes a configure function that sets and runs the assembly process. All you need to do is provide the converter.

Primer

An exporter is an Antora extension. Thus, to start, you create the basic structure of an Antora extension.

module.exports.register = function ({ config }) {}

Next, you define a converter. A converter consists of the following properties:

convert: A function that converts the assembly file to the target format. Typically, this function passes the AsciiDoc source (by way of stdin) to an external command such as asciidoctor-pdf to convert it to the target format. You can use Antora’s runCommand helper function to invoke the external command.
getDefaultCommand: An optionally async function that returns the default command to use when no command is specified in the config. (optional)
backend: The target backend; the backend that will be set during conversion (e.g., epub). (optional, default: the file extension without the leading dot)
extname: The file extension of the target format (e.g., .epub).
mediaType: The MIME type of the target format (e.g., application/epub+zip).
embedReferenceStyle: Controls whether images are rewritten relative to the export file (relative) or the output directory (output-relative). The docdir attribute passed to the convert function is set accordingly. (optional, default: relative)

This setting is not used when exporting to HTML (since images are linkable resources in that case). Instead, the link_reference_style key on the Assembler configuration is used.
loggerName: The name of the Antora logger to use when logging messages captured from stderr of the command (e.g., @antora/epub-extension). (optional, default: @antora/assembler)

const converter = {
  convert,
  backend: 'ext',
  extname: '.ext',
  mediaType: 'application/ext',
  loggerName: 'ext-exporter-extension',
}

The optional getDefaultFunction has the following API:

async function getDefaultCommand (cwd)

The convert function has the following API:

async function convert (file, convertAttributes, buildConfig)

The file parameter is the assembly file. You’re typically only interested in the file.contents property, which contains the AsciiDoc source buffer. The convertAttributes parameter is an object of AsciiDoc attributes to pass to the converter. These attributes can be converted to CLI options by calling .toArgs('-a', command), where -a is the CLI option flag and command is the external command. The buildConfig parameter provides both the command and the cwd.

Remember that the convert function should pass the stderr key on the buildConfig object to the runCommand helper and return its result in order for the built-in stderr handling to work.

If the converter object does not include the getDefaultCommand function, the command property on the buildConfig object could be undefined.

You then pass generator context, converter, and extension config to the configure function provided by Assembler.

this.require('@antora/assembler').configure(this, converter, config)

Here’s how it looks all together:

module.exports.register = function ({ config }) {
  const converter = {
    convert,
    backend: 'ext',
    extname: '.ext',
    mediaType: 'application/ext',
    loggerName: 'ext-exporter-extension',
  }
  this.require('@antora/assembler').configure(this, converter, config)
}

The example in the next section provides a full working implementation.

Example: DocBook

Here’s an example of how to create a DocBook extension that uses Asciidoctor by default.

Example 1. docbook-exporter-extension.js

'use strict'

const runCommand = require('@antora/run-command-helper')
const fsp = require('node:fs/promises')
const ospath = require('node:path')

const DEFAULT_COMMAND = 'asciidoctor -b docbook'

module.exports.register = function ({ config }) {
  const converter = {
    convert,
    backend: 'docbook',
    getDefaultCommand,
    extname: '.xml',
    mediaType: 'application/docbook+xml',
  }
  this.require('@antora/assembler').configure(this, converter, config)
}

async function convert (doc, convertAttributes, buildConfig) {
  const { command, cwd = process.cwd(), stderr = 'print' } = buildConfig
  const args = convertAttributes
    .toArgs('-a', command)
    .concat('-o', convertAttributes.outfile, '-')
  return runCommand(
    command,
    args,
    { parse: true, cwd, stdin: doc.contents, stdout: 'print', stderr }
  )
}

function getDefaultCommand (cwd) {
  return fsp.access(ospath.join(cwd, 'Gemfile.lock')).then(
    () => `bundle exec ${DEFAULT_COMMAND}`,
    () => DEFAULT_COMMAND
  )
}

Notice that the extension delegates to Assembler to configure itself. It passes the convert function alongside metadata about the target format.

An exporter extension currently has to depend on Antora’s runCommand helper package (@antora/run-command-helper). In the future, it will be possible to retrieve this function from the bound generator context (e.g., this.getHelpers().runCommand).

Example: DocBook PDF

DocBook isn’t a format most visitors of the site are going to be able to view. Unless your only goal is to export the content from Antora, you probably want to convert to an end-user format such as PDF by way of DocBook.

It’s possible to have the convert function run two consecutive commands, one to convert from AsciiDoc to AsciiDoc and one to convert from DocBook to PDF. (Alternately, you could write a script that combines both steps into a single call).

Here’s an updated version of the DocBook exporter that takes the conversion all the way to PDF.

Example 2. docbook-pdf-exporter-extension.js

'use strict'

const runCommand = require('@antora/run-command-helper')
const fsp = require('node:fs/promises')
const ospath = require('node:path')

const DEFAULT_COMMAND = 'asciidoctor -b docbook'

module.exports.register = function ({ config }) {
  const converter = {
    convert,
    backend: 'pdf',
    getDefaultCommand,
    extname: '.pdf',
    mediaType: 'application/pdf',
  }
  this.require('@antora/assembler').configure(this, converter, config)
}

async function convert (doc, convertAttributes, buildConfig) {
  const { command, cwd = process.cwd(), stderr = 'print' } = buildConfig
  const outfilePdf = convertAttributes.outfile
  convertAttributes.outfile = convertAttributes.outfile.replace(
    new RegExp(`\\${convertAttributes.outfilesuffix}$`),
    (convertAttributes.outfilesuffix = '.xml')
  )
  const args = convertAttributes
    .toArgs('-a', command)
    .concat('-o', convertAttributes.outfile, '-')
  return runCommand(
    command,
    args,
    { parse: true, cwd, stdin: doc.contents, stdout: 'print', stderr }
  ).then(() => {
    return runCommand(
      'fopub',
      ['-f', 'pdf', convertAttributes.outfile],
      { cwd, stdout: 'print', stderr },
    ).then((returnValue) => {
      convertAttributes.outfile = outfilePdf
      return returnValue
    })
  })
}

function getDefaultCommand (cwd) {
  return fsp.access(ospath.join(cwd, 'Gemfile.lock')).then(
    () => `bundle exec ${DEFAULT_COMMAND}`,
    () => DEFAULT_COMMAND
  )
}

This exporter uses a DocBook toolchain frontend named fopub to convert from DocBook to PDF. You can use whatever application works best for you (e.g., xmlto).

The convert function does have to do some fiddling with the outfile and outfilesuffix attributes so they have the correct values when converting to DocBook. The return value of the first command is also ignored, so some work probably needs to be done to fuse the stderr from both commands.