Convert EPUB3 to AsciiDoc

Why Convert EPUB3 to AsciiDoc?

Converting EPUB3 e-books to AsciiDoc format enables you to extract rich e-book content into a powerful, editable markup language that supports professional publishing workflows. While EPUB3 is excellent for distributing digital books, AsciiDoc provides the authoring environment needed to maintain and evolve content over time.

EPUB3 files contain HTML5 documents packaged in a ZIP archive with metadata, stylesheets, and media assets. By converting to AsciiDoc, you gain a single-source authoring format from which you can regenerate EPUB3, PDF, HTML5, and other output formats. This is particularly valuable for technical publishers who need to maintain content across multiple editions.

AsciiDoc's syntax is more expressive than Markdown while remaining readable as plain text. It natively supports features critical for technical publishing: admonitions, cross-references, bibliography management, conditional content, and modular includes. These capabilities make it the preferred format for organizations like the Eclipse Foundation, Red Hat, and O'Reilly Media.

During conversion, EPUB3 chapter structure, text formatting, lists, tables, and images are mapped to their AsciiDoc equivalents. The semantic structure of the EPUB3 is preserved through AsciiDoc's heading hierarchy and section organization, ensuring that the converted content maintains its logical structure.

Key Benefits of Converting EPUB3 to AsciiDoc:

• Professional Publishing: Used by O'Reilly and other major publishers
• Single-Source Authoring: Generate EPUB3, PDF, HTML5 from one source
• Version Control: Plain text format works perfectly with Git
• Rich Feature Set: Admonitions, cross-references, includes, conditionals
• Platform Integration: Native rendering on GitHub and GitLab
• Modular Content: Split large books into manageable included files
• Extensible: Custom macros and extensions for specialized needs

Practical Examples

Example 1: Book Chapter with Admonitions

Input EPUB3 content (chapter.xhtml):

<section epub:type="chapter">
  <h1>Security Best Practices</h1>
  <p>Always validate user input before
  processing it in your application.</p>
  <aside class="warning" epub:type="notice">
    <p>Never store passwords in plain text.
    Use bcrypt or argon2 for hashing.</p>
  </aside>
  <h2>Authentication</h2>
  <p>Implement <strong>multi-factor
  authentication</strong> for sensitive operations.</p>
</section>

Output AsciiDoc file (chapter.asciidoc):

= Security Best Practices

Always validate user input before
processing it in your application.

WARNING: Never store passwords in plain text.
Use bcrypt or argon2 for hashing.

== Authentication

Implement *multi-factor
authentication* for sensitive operations.

Example 2: Technical Content with Code Listings

Input EPUB3 content (tutorial.xhtml):

<h2>Database Setup</h2>
<p>Create the configuration file:</p>
<pre><code class="language-yaml">
database:
  host: localhost
  port: 5432
  name: myapp
</code></pre>
<p>Then run the migration:</p>
<pre><code class="language-bash">
python manage.py migrate
</code></pre>

Output AsciiDoc file (tutorial.asciidoc):

== Database Setup

Create the configuration file:

[source,yaml]
----
database:
  host: localhost
  port: 5432
  name: myapp
----

Then run the migration:

[source,bash]
----
python manage.py migrate
----

Example 3: Cross-References and Footnotes

Input EPUB3 content (reference.xhtml):

<h2 id="sec-overview">System Overview</h2>
<p>The architecture is described in
<a href="#sec-details">Section 2</a>.</p>
<p>This approach was first proposed by
Smith<a epub:type="noteref" href="#fn1">1</a>.</p>
<aside id="fn1" epub:type="footnote">
  <p>Smith, J. (2020). Modern Architecture.</p>
</aside>
<h2 id="sec-details">Architecture Details</h2>
<p>See <a href="#sec-overview">Section 1</a>
for an introduction.</p>

Output AsciiDoc file (reference.asciidoc):

[[sec-overview]]
== System Overview

The architecture is described in
<<sec-details>>.

This approach was first proposed by
Smithfootnote:[Smith, J. (2020). Modern Architecture.].

[[sec-details]]
== Architecture Details

See <<sec-overview>>
for an introduction.

Frequently Asked Questions (FAQ)

Q: What is AsciiDoc format?

A: AsciiDoc is a lightweight yet powerful markup language for writing technical documentation, books, and articles. It uses .asciidoc (or .adoc) file extensions and is processed by Asciidoctor to produce HTML5, PDF, EPUB3, DocBook, and other formats. It offers more features than Markdown while maintaining human readability.

Q: How does AsciiDoc differ from ADOC?

A: AsciiDoc and ADOC refer to the same markup language. The .asciidoc extension is the full form, while .adoc is the commonly used abbreviated extension. Both are processed identically by Asciidoctor. The choice of extension is a matter of preference or project convention.

Q: Will the EPUB3 chapter structure be preserved?

A: Yes, the EPUB3 spine order and chapter hierarchy are mapped to AsciiDoc heading levels. Each EPUB3 chapter becomes a section in the AsciiDoc document, maintaining the original book structure. You can also split the output into separate files using AsciiDoc's include directive for modular management.

Q: Can AsciiDoc handle EPUB3's MathML content?

A: AsciiDoc supports STEM (Science, Technology, Engineering, Math) content through Asciidoctor's built-in math support. MathML expressions from EPUB3 can be converted to LaTeX-style math notation in AsciiDoc STEM blocks, which are rendered using MathJax or KaTeX in HTML output.

Q: Is AsciiDoc better than Markdown for books?

A: For book-length content, AsciiDoc is generally superior to Markdown. It natively supports cross-references between chapters, footnotes, bibliography, index terms, admonitions, and conditional content. These features are essential for technical books and are why publishers like O'Reilly Media chose AsciiDoc as their authoring format.

Q: How are EPUB3 metadata and cover images handled?

A: EPUB3 metadata (title, author, publisher, ISBN) is converted to AsciiDoc document attributes in the header. Cover images are extracted and referenced using AsciiDoc image macros. This metadata is used by Asciidoctor when regenerating EPUB or PDF output.

Q: Can I use AsciiDoc with continuous integration?

A: Yes, Asciidoctor integrates seamlessly with CI/CD pipelines. You can automate the generation of EPUB3, PDF, and HTML documentation on every commit. Asciidoctor is available as Ruby gem, npm package (asciidoctor.js), and Java library (AsciidoctorJ), supporting all major build systems.

Q: What about EPUB3 interactive elements?

A: EPUB3 supports JavaScript-based interactivity, which has no direct equivalent in AsciiDoc. Interactive elements are converted to static content descriptions or placeholder blocks. For web output, Asciidoctor extensions can add interactive features, but the static nature of AsciiDoc makes it more focused on content rather than interactivity.