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

epub3

extname

.epub

mediaType

application/epub+zip

default command

asciidoctor-epub3 (prefixed with bundle exec if Gemfile.lock is present)

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.

Known issues

XML-compliant IDs

EPUB mandates XML compliance. That means that all ids must conform to the idname form. To get Assembler to generate ids that are XML compliant, you must set the xml_ids key to true in the Assembler configuration.

Example 1. antora-assembler-epub.yaml
assembly:
  xml_ids: true

Refer to xml_ids for more information about this key.