@antora/epub-extension 1.0.0-beta.1

package/README.md

@@ -0,0 +1,30 @@
+# Antora EPUB Extension
+
+The Antora EPUB 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 EPUB format (specifically EPUB3).
+This extension is the official extension for exporting content in an Antora site to EPUB.
+
+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 EPUB using Asciidoctor EPUB3 (or the specified command).
+Finally, Assembler adds those EPUBs to the content catalog as exports, which Antora then publishes alongside the other files in the site.
+
+## Usage
+
+Once this package is installed in the playbook project, register it in the Antora playbook as follows:
+
+**antora-playbook.yml**
+
+```yaml
+antora:
+  extensions:
+  - '@antora/epub-extension'
+# ...
+```
+
+You can configure the behavior of the extension using the optional _antora-assembler.yml_ file.
+
+## Copyright and License
+
+Copyright (C) 2022-present by OpenDevise Inc. and the individual contributors of this project.
+
+Use of this software is granted under the terms of the [Mozilla Public License Version 2.0](https://www.mozilla.org/en-US/MPL/2.0/) (MPL-2.0).

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-epub3'
+
+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: 'epub3',
+  extname: '.epub',
+  mediaType: 'application/epub+zip',
+}

package/lib/index.js

@@ -0,0 +1,15 @@
+'use strict'
+
+const converter = require('./converter')
+const runCommand = require('@antora/run-command-helper')
+
+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

@@ -0,0 +1,53 @@
+{
+  "name": "@antora/epub-extension",
+  "version": "1.0.0-beta.1",
+  "description": "An Antora extension that uses Assembler to merge pages into assembly files, export them to the EPUB format, and publishe them with the site.",
+  "license": "MPL-2.0",
+  "author": "OpenDevise Inc. (https://opendevise.com)",
+  "contributors": [
+    "Dan Allen <dan@opendevise.com>",
+    "Sarah White <sarah@opendevise.com>"
+  ],
+  "homepage": "https://antora.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/antora/antora-assembler.git",
+    "directory": "packages/epub-extension"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/antora/antora-assembler/issues"
+  },
+  "scripts": {
+    "test": "node --test test/*-test.js",
+    "prepublishOnly": "npx -y downdoc --prepublish",
+    "postpublish": "npx -y downdoc --postpublish"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./converter": "./lib/converter.js",
+    "./package.json": "./package.json"
+  },
+  "imports": {
+    "#package": "./package.json"
+  },
+  "dependencies": {
+    "@antora/assembler": "1.0.0-beta.1",
+    "@antora/run-command-helper": "~1.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "lib/"
+  ],
+  "keywords": [
+    "antora",
+    "antora-extension",
+    "asciidoc",
+    "asciidoctor",
+    "epub",
+    "generator",
+    "documentation"
+  ]
+}