How to Convert AsciiDoc to EPUB3 with Asciidoctor

Asciidoctor EPUB3 aims to produce EPUB3 documents that meet the following objectives:

We believe that the e-books produced by Asciidoctor EPUB3 are the very best output you can expect to find in digital publishing today. Of course, there’s always room for improvement, so we’ll continue to work with you to achieve and maintain this goal.

Asciidoctor EPUB3 is currently alpha software. Use accordingly. Although the bulk of AsciiDoc content is rendered, there’s still work needed to fill in gaps where rendering is incomplete or unstyled.

See the WORKLOG.

Asciidoctor relies on top-level include directives (i.e., include directives in the master document) to indicate where the chapter splits should occur. In other words, you must be explicit. Asciidoctor will not try to guess. If your AsciiDoc document is not structured in this way, you’ll need to change it to use the Asciidoctor EPUB3 converter properly.

You can think of the master document as the spine of the book and the include directives as the individual items being bound together. The target of each include directive in the master document is parsed and rendered as a separate AsciiDoc document, with certain options and attributes being passed down from the master to ensure consistent behavior. Each resulting XHTML document is then added to the EPUB3 archive as a chapter document and the master document becomes the navigation file (i.e., the table of contents).

If the master document does not contain any include directives, then the converter treats the document as the sole chapter in the EPUB3 archive and automatically produces a navigation file that references it.

Eventually, we envision introducing a dedicated block macro to represent a spine item so that we don’t overload the meaning of the include directive. However, for the time being, the include directive will suit this purpose.

You can retrieve Asciidoctor EPUB3 in one of two ways:

The dependencies needed to use Asciidoctor EPUB3 are defined in the Gemfile at the root of the project. We can use Bundler to install the dependencies for us.

To check if you have Bundler available, use the bundle command to query the version installed.

If it’s not installed, use the gem command to install it.

Then use the bundle command to install the project dependencies.

Now that the dependencies are installed, you can build and install the Gem.

Use the Rake build tool to build the Gem.

The build will report that it built the Gem into the pkg directory.

Finally, install the Gem.

You’re now ready to use Asciidoctor EPUB3! Let’s get an AsciiDoc document ready to convert to EPUB3.

If you don’t already have an AsciiDoc document, you can use the sample-book.adoc file and its chapters found in the data/samples directory of the repository.

The metadata in the generated EPUB3 file is populated from attributes in the AsciiDoc document. The names of the attributes and the metadata elements to which they map are documented in this section.

The term package metadata in Table 1 is in reference to the <metadata> element in the EPUB3 package document (e.g., package.opf). The dc namespace prefix is in reference to the Dublin Core Metadata Element Set.

When using the EPUB3 converter, the ebook-format attribute resolves to the name of the e-book format being generated (epub3 or kf8) and the corresponding attribute ebook-format-<name> is defined, where <name> is epub3 or kf8. You can use these attributes in a preprocessor directive if you only want to show certain content to readers using a particular device. For instance, if you want to display a message to readers on Kindle, you can use:

With that out of the way, it’s time to convert the AsciiDoc document directly to EPUB3.

Converting an AsciiDoc document to EPUB3 is as simple as passing your document to the asciidoctor-epub3 command. This command should be available on your PATH if you installed the asciidoctor-epub3 gem. Otherwise, you can find the command in the bin folder of the project. We also recommend specifying an output directory using the -D option flag.

When the script completes, you’ll see the file sample-book.epub appear in the output directory. Open that file with an EPUB3 reader to view the result.

Below are several screenshots of this sample book as it appears on an Android phone.

Next, let’s validate the EPUB3 archive to ensure it built correctly.

If the EPUB3 archive contains any errors, they will be output in your terminal.

If you want to browse the contents of the EPUB3 file that is generated, or preview the XHTML files in a regular web browser, add the -a ebook-extract flag to the asciidoctor-epub3 command. The EPUB3 file will be extracted to a directory adjacent to the generated file, but without the file extension.

In this example, the contents of the EPUB3 will be extracted to the output/sample-book directory.

Creating a KF8/MOBI archive directly from an AsciiDoc document is done with the same generation script (asciidoctor-epub3). You just need to specify the format (-a ebook-format) as kf8.

When the script completes, you’ll see the file sample-book.mobi appear in the output directory.

KindleGen does mandatory validation so you don’t need to run the validate command after converting to KF8/MOBI.

Here’s a sample manifest of files found in an EPUB3 document produced by Asciidoctor EPUB3.

E-book readers have different image resolution and file size limits regarding a book’s cover. Kindle covers tend to be 1050x1600 (16:9 resolution), which is the size of the sample cover provided with Asciidoctor EPUB3. To ensure your cover displays correctly, you’ll want to review the documentation or publisher guidelines for the application you’re targeting.

Feel free to use the SVG of the sample cover in the data/images folder as a template for creating your own cover. Once your image is ready, you can replace the placeholder cover image by defining the front-cover-image attribute in the header of the master document.

The image is resolved relative to the directory specified in the imagesdir attribute, which defaults to the document directory. The image can be in any format, though we recommend using PNG or JPG as they are the most portable formats.

Asciidoctor EPUB3 embeds a set of fonts and font icons. The theme’s fonts are located in the data/fonts directory.

The M+ Outline fonts are used for titles, headings, literal (monospace) text, and annotation numbers. The body text uses Noto Serif. Admonition icons and the end-of-chapter mark are from the Font Awesome icon font. Refer to the NOTICE for further information about the fonts.

Many of the EPUB3 readers use the WebKit browser engine to render the content and apply the CSS formatting and styles. Generally speaking, WebKit is a great engine that brings a lot of consistency and power to the e-book reader landscape. It also brings along the same set of bugs.

One of the bugs in WebKit causes rich text to be justified incorrectly. In particular, when the value of the text-align property is justify, WebKit drops the space between formatted text (bold, italic, hyperlink, etc) and non-formatted text, causing the words to be unevenly spaced across the line. You can see an example of this problem in the screenshot below.

It’s not terrible, but just enough to disrupt a reader’s flow. Here’s how we expect the text to look:

After some time in the tech lab and some dumb luck, we found a way to trick WebKit into justifying the text correctly! We call it the “word joiner hack”.

Here’s the HTML source of the first sentence from the screenshots.

WebKit treats the space following an inline element as insignificant and thus fails to account for it when justifying the text.

At first glance, you might think to add a normal space character before the closing tag of the inline element (e.g., <a href="…​">Fork </a>). However, that would cause any underline beneath links to extend past the end of the word.

At second glance, you might think to add a zero-width space character immediately following the element (e.g., <a href="…​">Fork</a>​). However, that’s problematic if the next character is a period or other punctuation because it introduces a wrap opportunity where there shouldn’t be one.

Reflecting on the problem of the zero-width space brings us to either the zero-width no-break space character (e.g., <a href="…​">Fork</a>&#xfeff) or the word joiner character (e.g., <a href="…​">Fork</a>⁠). Like the zero-width space, these characters occupy no space. However, instead of introducing a wrap opportunity, they prevent one.

But here’s the clincher. If the character following a zero-width non-break space or a word joiner is a normal space (e.g., <a href="…​">Fork</a> the), then it behaves just like a regular space. We’ve covered all the scenarios! Hey WebKit, you’ve been Unicode punked!

UPDATE: The zero-width no-break space was deprecated in favor of the word joiner. However, as we’ve discovered, font support for the word joiner is abysmal, whereas the zero-width no-break space is supported everywhere we’ve checked. Therefore, we’ve decided to go with the zero-width no-break space to avoid nasty rectangle outlines from font bombing your content.

By adding the word joiner zero-width no-break space character immediately after any inline element, we can trick WebKit into justifying the text properly, as shown in the second screenshot above.

Although the fix may seem minor enhancement, it plays an important role in reaching one of the core objectives of this converter: to make the text in the EPUB3 as readable as possible.

For readers that support JavaScript, Asciidoctor EPUB3 adds a CSS class to the body element of each chapter that corresponds to the name of the reader as reported by the epubReadingSystem JavaScript object. This enhancement allows you to use styles targeted specifically at that reader.

Below you can find the readers that are known to support this feature and the CSS class name that gets added to the body element.