Convert AsciiDoc to EPUB

Why Convert AsciiDoc to EPUB?

Converting AsciiDoc to EPUB is a proven workflow used by major technical publishers including O'Reilly Media, which has long used AsciiDoc as their preferred authoring format for producing EPUB ebooks. This conversion transforms your plain-text AsciiDoc markup into a polished, navigable ebook that can be read on virtually any e-reader device, tablet, phone, or computer. The Asciidoctor project provides a dedicated EPUB3 converter (asciidoctor-epub3) specifically designed for this workflow.

EPUB (Electronic Publication) is the most widely supported open ebook standard, maintained by the W3C. EPUB files contain XHTML content, CSS stylesheets, images, and metadata in a ZIP package. The format supports reflowable text that adapts to any screen size, embedded fonts for professional typography, navigable table of contents from AsciiDoc headings, and accessibility features for readers with disabilities. EPUB 3, the current version, is based on HTML5 and CSS3.

The AsciiDoc-to-EPUB conversion preserves the rich structure of your documentation. Chapter headings create navigable sections, code blocks maintain their formatting with monospaced fonts, admonitions become styled callout boxes, tables are rendered as HTML tables, images are embedded in the EPUB package, and cross-references become clickable links. The result is a professional ebook that maintains the full structure and readability of your source documentation.

EPUB ebooks created from AsciiDoc can be distributed through Apple Books, Google Play Books, Kobo, Barnes and Noble (Nook), public libraries (via OverDrive), and any platform that supports the EPUB standard. For Amazon Kindle distribution, the EPUB can be further converted to AZW3/KF8 format using Calibre or Amazon's KindleGen tool. This makes AsciiDoc a true single-source format for producing ebooks across all major platforms.

Key Benefits of Converting AsciiDoc to EPUB:

• Professional Ebooks: Produce publication-quality ebooks from plain text
• Open Standard: EPUB is a W3C standard supported by all major platforms
• Reflowable Text: Content adapts to any screen size and font preference
• Navigation: AsciiDoc headings create navigable table of contents
• Code Blocks: Technical code listings rendered with proper formatting
• Multi-Platform: Read on Apple Books, Kobo, Nook, and hundreds of apps
• Publisher Workflow: Proven by O'Reilly Media for technical book publishing

Practical Examples

Example 1: Technical Book with Chapters

Input AsciiDoc file (python-book.adoc):

= Learn Python Programming
Jane Developer
:doctype: book
:toc:
:front-cover-image: cover.png

[preface]
== Preface

This book teaches Python from scratch.

== Variables and Data Types

Python variables are _dynamically typed_.

[source,python]
----
name = "Alice"
age = 30
is_active = True
----

TIP: Use type hints for better code clarity.

Output EPUB file (python-book.epub):

Professional EPUB ebook:
- Cover image on first page
- Preface as front matter
- Navigable table of contents
- Chapter: Variables and Data Types
- Italic formatting preserved
- Styled Python code block
- Tip callout with icon
- Reflowable on all screen sizes
- Ready for Apple Books, Kobo, etc.

Example 2: Documentation for Offline Reading

Input AsciiDoc file (admin-guide.adoc):

= System Administration Guide
:author: DevOps Team
:toc:

== Server Setup

=== Hardware Requirements

|===
| Component | Minimum | Recommended
| CPU | 4 cores | 8 cores
| RAM | 16 GB | 32 GB
| Storage | 100 GB SSD | 500 GB NVMe
|===

WARNING: Never run in production without backups.

Output EPUB file (admin-guide.epub):

Offline-ready ebook:
- Structured chapter navigation
- Requirements table with formatting
- Warning callout clearly displayed
- Searchable content
- Bookmarkable sections
- Read on tablet during maintenance
- No internet connection needed
- Easy to distribute to team

Example 3: Self-Published Tutorial Series

Input AsciiDoc file (web-dev.adoc):

= Web Development Fundamentals
:author: Tech Writer
:email: [email protected]
:doctype: book

== HTML Basics

HTML is the *foundation* of the web.

[source,html]
----
<!DOCTYPE html>
<html>
<head><title>My Page</title></head>
<body><h1>Hello</h1></body>
</html>
----

NOTE: Always use semantic HTML elements.

Output EPUB file (web-dev.epub):

Self-published ebook:
- Author and contact metadata
- Book-style chapter layout
- HTML code block with formatting
- Note callout for key concepts
- Ready for Apple Books publishing
- Distributable via Gumroad/Leanpub
- Convertible to Kindle (AZW3)
- Professional appearance

Frequently Asked Questions (FAQ)

Q: What is EPUB format?

A: EPUB (Electronic Publication) is an open ebook standard maintained by the W3C. EPUB files are ZIP archives containing XHTML content, CSS stylesheets, images, and metadata. The format supports reflowable text, embedded fonts, accessibility features, and multimedia (EPUB 3). It is the most widely supported ebook format outside the Amazon Kindle ecosystem.

Q: Does Asciidoctor have a dedicated EPUB converter?

A: Yes, the asciidoctor-epub3 gem is a dedicated converter that produces EPUB 3 files directly from AsciiDoc source. It generates valid EPUB 3 ebooks with proper navigation, metadata, styling, and chapter structure. Alternatively, you can convert AsciiDoc to DocBook first, then use Pandoc or other tools to generate EPUB.

Q: Can I read EPUB files on a Kindle?

A: Amazon Kindle devices do not natively support EPUB. However, recent Kindle models support the Send to Kindle feature which can convert EPUB to Kindle format. Alternatively, you can convert EPUB to AZW3 using Calibre or Amazon's tools. For direct Kindle compatibility, consider our AsciiDoc to AZW3 conversion instead.

Q: How are AsciiDoc code blocks displayed in EPUB?

A: AsciiDoc source code blocks are converted to styled <pre> elements in the EPUB's XHTML content, typically with a monospaced font and background color. EPUB readers render these as formatted code blocks. Syntax highlighting depends on the converter and CSS used. On small screens, long code lines may wrap.

Q: Can I add a cover image to the EPUB?

A: Yes. In your AsciiDoc source, use the :front-cover-image: attribute to specify a cover image file. The converter will embed this image as the EPUB cover page, which is displayed in e-reader libraries and bookstores. Recommended cover image dimensions are at least 1600x2400 pixels for high-quality display.

Q: Where can I distribute EPUB ebooks?

A: EPUB ebooks can be distributed through Apple Books, Google Play Books, Kobo, Barnes and Noble (Nook), OverDrive (libraries), Smashwords, Draft2Digital, Leanpub, Gumroad, and many other platforms. EPUB is the universal ebook format accepted by all major distributors except Amazon (which prefers EPUB or KPF for KDP).

Q: What is the difference between EPUB 2 and EPUB 3?

A: EPUB 2 uses XHTML 1.1 and limited CSS, while EPUB 3 is based on HTML5 and CSS3, supporting embedded fonts, SVG, MathML, JavaScript interactivity, audio/video, and enhanced accessibility. EPUB 3 is the current standard and is recommended for all new ebooks. Most modern e-readers support EPUB 3.

Q: Can I publish an AsciiDoc book on O'Reilly's platform?

A: Yes, O'Reilly Media accepts AsciiDoc as a source format and has their own toolchain for producing EPUB, PDF, and other formats. If you are self-publishing, you can use Asciidoctor to convert your AsciiDoc book to EPUB and distribute it through O'Reilly's learning platform or other channels.