Convert EPUB3 to ADOC

Why Convert EPUB3 to ADOC?

Converting EPUB3 e-books to AsciiDoc (ADOC) format is valuable when you need to extract and repurpose e-book content for technical documentation workflows. While EPUB3 excels at digital book distribution with rich multimedia and interactive features, AsciiDoc provides a lightweight, editable format ideal for maintaining content in version-controlled repositories.

EPUB3 files are essentially ZIP archives containing HTML5, CSS3, images, and metadata. By converting to AsciiDoc, you transform this complex package into clean, human-readable plain text that can be easily edited, reviewed, and tracked using Git. This makes the content accessible to teams that work with documentation-as-code approaches.

AsciiDoc is particularly well-suited as a target format because it can regenerate EPUB output when needed. Publishers like O'Reilly Media use AsciiDoc as their authoring format, producing EPUB, PDF, and HTML from a single source. Converting EPUB3 to ADOC gives you this single-source publishing capability.

During conversion, the HTML5 content within the EPUB3 is parsed and transformed into equivalent AsciiDoc syntax. Chapter structure, headings, lists, tables, and text formatting are preserved. Embedded images can be extracted and referenced in the AsciiDoc output. However, interactive JavaScript elements and complex CSS styling may not have direct AsciiDoc equivalents.

Key Benefits of Converting EPUB3 to ADOC:

• Editable Content: Transform binary e-book packages into editable plain text
• Version Control: Track changes with Git and collaborate on content
• Single-Source Publishing: Regenerate EPUB, PDF, and HTML from AsciiDoc
• Platform Rendering: GitHub and GitLab render ADOC files natively
• Documentation Reuse: Repurpose e-book content for technical docs
• Include System: Modular documentation with file includes
• Modern Tooling: Asciidoctor integrates with build systems and CI/CD

Practical Examples

Example 1: E-Book Chapter Conversion

Input EPUB3 content (chapter1.xhtml):

<section epub:type="chapter">
  <h1>Getting Started</h1>
  <p>This chapter covers the basics of
  setting up your development environment.</p>
  <h2>Prerequisites</h2>
  <ul>
    <li>Python 3.8 or higher</li>
    <li>A text editor</li>
    <li>Git version control</li>
  </ul>
</section>

Output ADOC file (chapter1.adoc):

= Getting Started

This chapter covers the basics of
setting up your development environment.

== Prerequisites

* Python 3.8 or higher
* A text editor
* Git version control

Example 2: Formatted Content with Images

Input EPUB3 content (section.xhtml):

<h2>Architecture Overview</h2>
<p>The system uses a <strong>microservices</strong>
architecture as shown in <a href="#fig-arch">Figure 1</a>.</p>
<figure id="fig-arch">
  <img src="images/architecture.png"
       alt="System Architecture"/>
  <figcaption>System Architecture Diagram</figcaption>
</figure>
<p>Key components include:</p>
<ol>
  <li>API Gateway</li>
  <li>Service Registry</li>
  <li>Message Queue</li>
</ol>

Output ADOC file (section.adoc):

== Architecture Overview

The system uses a *microservices*
architecture as shown in <<fig-arch>>.

[[fig-arch]]
.System Architecture Diagram
image::images/architecture.png[System Architecture]

Key components include:

. API Gateway
. Service Registry
. Message Queue

Example 3: Table and Code Block Conversion

Input EPUB3 content (reference.xhtml):

<h2>API Reference</h2>
<table>
  <thead>
    <tr><th>Method</th><th>Endpoint</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr><td>GET</td><td>/api/users</td><td>List users</td></tr>
    <tr><td>POST</td><td>/api/users</td><td>Create user</td></tr>
  </tbody>
</table>
<pre><code class="language-python">
import requests
response = requests.get("/api/users")
</code></pre>

Output ADOC file (reference.adoc):

== API Reference

|===
|Method |Endpoint |Description

|GET |/api/users |List users
|POST |/api/users |Create user
|===

[source,python]
----
import requests
response = requests.get("/api/users")
----

Frequently Asked Questions (FAQ)

Q: What is EPUB3 format?

A: EPUB3 (Electronic Publication 3.0) is the latest major version of the EPUB e-book standard, maintained by the W3C. It uses HTML5 for content, CSS3 for styling, and supports MathML, SVG, JavaScript interactivity, audio, video, and advanced accessibility features. It is the most widely supported open e-book format.

Q: Will images from the EPUB3 be preserved?

A: Yes, images embedded in the EPUB3 are extracted and referenced in the AsciiDoc output using image macros. The image files are saved alongside the ADOC file, maintaining the visual content of the original e-book in the converted document.

Q: How is the EPUB3 table of contents handled?

A: The EPUB3 navigation document (nav.xhtml) and chapter structure are converted into AsciiDoc heading levels. EPUB3 spine order is preserved, so chapters appear in the correct sequence. AsciiDoc automatically generates a table of contents from the heading hierarchy.

Q: What happens to multimedia content (audio/video)?

A: EPUB3 supports embedded audio and video, but AsciiDoc has limited multimedia support. Audio and video references are converted to links or placeholder blocks in the AsciiDoc output. For web output, Asciidoctor extensions can render media elements.

Q: Can I convert the ADOC back to EPUB?

A: Yes, Asciidoctor has an EPUB3 converter (asciidoctor-epub3) that can generate EPUB3 output from AsciiDoc source files. This makes AsciiDoc an excellent authoring format for e-books, allowing you to edit content as plain text and regenerate the EPUB when needed.

Q: Are EPUB3 accessibility features preserved?

A: EPUB3 includes accessibility features like ARIA roles, semantic structure, and alternative text. AsciiDoc preserves semantic structure through its heading hierarchy and supports alt text for images. However, some EPUB3-specific accessibility metadata may need to be manually added back when regenerating EPUB output.

Q: How does the converter handle EPUB3 CSS styling?

A: EPUB3 CSS styling is not directly transferred to AsciiDoc, as AsciiDoc uses semantic markup rather than visual styling. Text formatting like bold, italic, and code spans are preserved through AsciiDoc syntax. Custom CSS styling can be applied later through Asciidoctor themes when generating output.

Q: Is AsciiDoc suitable for republishing e-books?

A: Absolutely. Major publishers like O'Reilly Media use AsciiDoc as their primary authoring format for technical books. AsciiDoc can produce EPUB3, PDF, and HTML5 output from a single source, making it ideal for multi-format publishing workflows.