EPUB Extension

The Antora EPUB extension is an exporter extension for Assembler that handles converting content prepared by Assembler to the EPUB format (specifically EPUB3) using Asciidoctor EPUB3 by default. The Antora EPUB extension is the official extension for exporting content in an Antora site to EPUB.

Summary

package name: @antora/epub-extension
require name: @antora/epub-extension
backend: epub
extname: .epub
mediaType: application/epub+zip
default configuration file: ./antora-assembler-epub.yml
default command: asciidoctor-epub3 (prefixed with bundle exec if bundle lockfile is present, honoring BUNDLE_LOCKFILE or BUNDLE_GEMFILE environment variable)

Description

The Antora EPUB extension is based on Antora Assembler. It provides the converter metadata and convert function that Assembler uses to export content. The rest is handled by Assembler itself.

Assembler constructs the content of assembly files from pages per component version using the navigation as a model. Using the converter provided by this extension, it then iterates over those assembly files and converts them to EPUB using Asciidoctor EPUB3 (or the specified command). Finally, it adds those EPUBs to the content catalog as exports, which Antora then publishes alongside the other files in the site.

Configuration

XML-compliant IDs

EPUB mandates XML compliance. That means all ids must conform to the idname form. Assembler automatically generates ids that are XML-compliant for this exporter by default.

If you don’t want to use XML-compliant ids, you must set the xml_ids key to false in the Assembler configuration.

Example 1. antora-assembler-epub.yml

assembly:
  xml_ids: false

Refer to xml_ids for more information about this key.