Convert AsciiDoc to EPUB3

Why Convert AsciiDoc to EPUB3?

Converting AsciiDoc to EPUB3 bridges the gap between technical writing and modern digital publishing. AsciiDoc's structured markup maps naturally to EPUB3's semantic HTML5 foundation, producing e-books that are accessible, richly formatted, and ready for distribution on any major reading platform. Authors who write in AsciiDoc can reach readers on Kindle, Apple Books, Kobo, and other devices without leaving their plain-text workflow.

EPUB3 is the current standard for digital publications, maintained by the W3C since 2017. Unlike its predecessor EPUB2, EPUB3 is built on HTML5 and CSS3, which means it supports embedded audio and video, SVG vector graphics, MathML for equations, JavaScript interactivity, and advanced accessibility features through ARIA roles and media overlays. These capabilities make EPUB3 ideal for technical books that need code listings, diagrams, and mathematical formulas.

AsciiDoc's feature set aligns remarkably well with EPUB3's capabilities. Admonition blocks become styled callouts, source code blocks retain syntax highlighting, cross-references transform into navigable hyperlinks, and the table of contents becomes an interactive navigation document. The conversion preserves the logical structure of your document, including chapter divisions, section hierarchy, and metadata like author name and publication date.

For technical publishers and self-publishing authors, the AsciiDoc-to-EPUB3 pipeline offers a professional-grade workflow. You can maintain your book's source in a Git repository, collaborate with co-authors using pull requests, and generate polished EPUB3 output ready for submission to Apple Books, Google Play, or direct distribution. The same AsciiDoc source can also produce PDF, HTML, and DocBook output, making it a true single-source publishing system.

Key Benefits of Converting AsciiDoc to EPUB3:

• Modern E-Book Standard: EPUB3 is the W3C-recommended format for digital publications
• Accessibility: Built-in ARIA roles and media overlay support for screen readers
• Multimedia Integration: Embed audio, video, and interactive elements
• Semantic Structure: Chapter and section hierarchy preserved from AsciiDoc
• Universal Distribution: Compatible with Apple Books, Google Play, Kobo, and more
• Code Highlighting: Source code blocks rendered with proper syntax coloring
• Single-Source Publishing: Same AsciiDoc source produces EPUB3, PDF, and HTML

Practical Examples

Example 1: Technical Book with Code Samples

Input AsciiDoc file (guide.adoc):

= Python Developer's Guide
Jane Smith <[email protected]>
:toc: left
:sectnums:
:source-highlighter: rouge

== Getting Started

Install Python from https://python.org.

[source,python]
----
def greet(name):
    return f"Hello, {name}!"
----

NOTE: Python 3.10+ is required.

Output EPUB3 file (guide.epub):

Professional e-book containing:
✓ Interactive table of contents (NCX + HTML nav)
✓ Syntax-highlighted code blocks
✓ Styled admonition (NOTE) callouts
✓ Author metadata embedded in OPF
✓ Section numbering preserved
✓ Reflowable layout for all screen sizes
✓ EPUB3 semantic epub:type attributes

Example 2: Multi-Chapter Documentation

Input AsciiDoc file (manual.adoc):

= Product User Manual
:doctype: book
:icons: font

== Installation

Follow these steps:

. Download the installer
. Run `setup.exe`
. Accept the license agreement

== Configuration

.Configuration Table
|===
| Setting | Default | Description

| timeout
| 30
| Connection timeout in seconds
|===

WARNING: Back up your data before proceeding.

Output EPUB3 file (manual.epub):

Structured e-book manual:
✓ Chapters split into separate XHTML files
✓ Ordered lists rendered correctly
✓ Tables with headers and styling
✓ Warning admonition with icon
✓ Book-type document structure
✓ Navigation document with landmarks
✓ Compatible with all EPUB3 readers

Example 3: Academic Paper with Cross-References

Input AsciiDoc file (paper.adoc):

= Machine Learning Fundamentals
:stem: latexmath

== Introduction

As shown in <<results>>, the model
achieves 95% accuracy.

[[results]]
== Experimental Results

The loss function is defined as:

[stem]
++++
L = -\sum_{i} y_i \log(\hat{y}_i)
++++

[bibliography]
== References
* [[[ref1]]] Smith, J. (2024). Deep Learning.

Output EPUB3 file (paper.epub):

Academic e-book with:
✓ Internal cross-references as hyperlinks
✓ Mathematical formulas via MathML
✓ Bibliography section with citations
✓ Section anchors for navigation
✓ Proper academic document structure
✓ Accessible equation rendering
✓ Suitable for academic distribution

Frequently Asked Questions (FAQ)

Q: What is EPUB3 and how does it differ from EPUB2?

A: EPUB3 is the latest version of the EPUB standard, built on HTML5, CSS3, and JavaScript instead of XHTML 1.1 and CSS 2.1 used by EPUB2. Key improvements include support for embedded audio/video, MathML for equations, SVG graphics, JavaScript interactivity, and comprehensive accessibility features via ARIA. EPUB3 also introduces fixed-layout mode for comics and children's books.

Q: Will my AsciiDoc code blocks be preserved in EPUB3?

A: Yes. Source code blocks with language annotations are converted to styled HTML pre/code elements in the EPUB3 output. Syntax highlighting is applied using CSS classes, so your code samples appear with proper coloring on readers that support CSS. The monospace formatting and indentation are fully preserved.

Q: Can I read the converted EPUB3 on Kindle?

A: Amazon Kindle natively uses MOBI/AZW formats, but newer Kindle devices and the Kindle app support EPUB. You can also convert the EPUB3 to MOBI/KF8 using Calibre for older Kindle devices. Alternatively, Amazon's KDP (Kindle Direct Publishing) accepts EPUB3 files for publishing on the Kindle store.

Q: Are AsciiDoc admonitions (NOTE, WARNING, TIP) converted?

A: Absolutely. AsciiDoc admonitions are converted to styled HTML blocks in the EPUB3 output. Each admonition type (NOTE, TIP, IMPORTANT, CAUTION, WARNING) receives appropriate CSS styling with distinct colors and optional icons, making them visually distinguishable in the e-book.

Q: Does the conversion preserve images and diagrams?

A: Yes. Images referenced in your AsciiDoc document are embedded in the EPUB3 package. EPUB3 supports JPEG, PNG, GIF, and SVG formats. SVG is particularly useful for technical diagrams as it scales perfectly on any screen size. Make sure image files are accessible at the paths specified in your AsciiDoc source.

Q: Is the table of contents interactive in EPUB3?

A: Yes. The AsciiDoc table of contents directive (:toc:) generates an interactive HTML navigation document in EPUB3. Readers can tap or click entries to jump directly to chapters and sections. EPUB3 uses an HTML5 nav element instead of EPUB2's NCX format, providing richer navigation capabilities.

Q: Can I include mathematical formulas?

A: Yes. AsciiDoc's stem (Science, Technology, Engineering, Math) blocks support LaTeX math notation, which is converted to MathML in EPUB3. Most modern EPUB3 readers render MathML natively. For readers without MathML support, formulas can alternatively be rendered as SVG images during conversion.

Q: How large are the resulting EPUB3 files?

A: EPUB3 files are ZIP-compressed, so text-only e-books are typically very small (under 1 MB). File size grows with embedded images, fonts, and multimedia. A technical book with code samples and diagrams might be 5-20 MB. AsciiDoc's efficient markup produces clean HTML, keeping the EPUB3 output compact.