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.

Missing section IDs

If Asciidoctor EPUB3 fails to convert the assembly file, you may need to set the sectids attribute from the build command, as shown here:

build:
  command: bundle exec asciidoctor-epub3 -a sectids

This is necessary when a top-level entry in the navigation (i.e., a chapter) is plain text rather than a reference to a page. In this case, Assembler turns of the generation of the ID for that chapter (since IDs are based on the resource name). This causes the converter to either crash or to create an invalid nav entry when trying to locate the chapter by ID. By setting the sectids attribute from the CLI using the -a sectids option, it forces Asciidoctor to generate an ID for the chapter, which the converter can then use.