Free online ASCIIDOC to EPUB converter

Ebook readers and publishing systems commonly require EPUB rather than an AsciiDoc source file. Converting the source preserves its headings, paragraphs, lists, links, images, and other structured content in a reflowable format that readers can open on phones, tablets, and dedicated ebook devices.

What the ASCIIDOC format is

AsciiDoc is a plain-text markup format for structured documents such as books, manuals, software documentation, articles, and README files. Authors write headings, lists, tables, links, code blocks, attributes, cross-references, and admonitions using readable text syntax instead of editing a binary document.

Common source extensions include .adoc, .asciidoc, and .asc. Asciidoctor and Asciidoc use these files to generate HTML, PDF, man pages, and EPUB documents. Developers usually encounter them in documentation repositories, static-site projects, Git-based projects, and documentation build systems.

What the EPUB format is

EPUB is a ZIP-based ebook package containing XHTML content, CSS stylesheets, metadata, navigation files, and optional images, fonts, and other resources. EPUB 3 supports semantic HTML, responsive layouts, navigation, audio or video, and right-to-left or vertical writing where the reading system supports those features.

Unlike a fixed-page PDF, EPUB content reflows to match the screen size, font settings, and orientation of the reading device. It is suitable for distributing long-form documentation or books through ebook readers and libraries, and for checking the result with EPUB-compatible applications.

How to convert ASCIIDOC to EPUB

Use Asciidoctor EPUB3

Asciidoctor EPUB3 is the most direct choice because it understands AsciiDoc-specific constructs instead of treating the source as generic markup. Install Ruby first if it is not already available, then install the converter:

gem install asciidoctor-epub3

From the directory containing the source file, run:

asciidoctor-epub3 book.adoc -o book.epub

Replace book.adoc with the actual filename. The converter reads the document header, included files, referenced images, attributes, and structural elements, then writes book.epub.

For a multi-file project, keep included sources and image directories in their expected relative locations. A typical command with a custom working directory is:

asciidoctor-epub3 -D output book.adoc

Set document metadata in the AsciiDoc header before conversion, for example:

= Book title
Author Name <author@example.com>
:revnumber: 1.0
:description: A short description
:doctype: book
:toc:
:sectnums:

Use an image attribute such as :imagesdir: images when image paths are relative to a common directory. Check that every referenced image exists and uses a format supported by the target reading systems, typically JPEG, PNG, or SVG.

Convert without installing software

You can convert the file for free on the 101convert.com website when installing Ruby or Asciidoctor is not practical. Upload the AsciiDoc file, choose EPUB as the output format, start the conversion, and download the generated ebook.

Use Pandoc as an alternative

Pandoc can convert some AsciiDoc documents directly:

pandoc book.adoc -o book.epub

Use Pandoc for comparatively simple documents or when it is already part of the publishing workflow. Asciidoctor EPUB3 generally preserves AsciiDoc-specific attributes, admonitions, includes, and cross-references more reliably.

Quality, compatibility, and limitations

EPUB is reflowable, so fixed line breaks, exact page positions, and PDF-style layout instructions cannot be preserved consistently. Page numbers, widows, orphan handling, and line wrapping vary by reading system and user font settings.

Complex AsciiDoc extensions, custom converters, embedded diagrams, unsupported macros, and PDF-only formatting may require manual adjustment. Generate diagram files before conversion and use relative paths for all local resources.

Open the result in at least one EPUB reader and inspect the table of contents, heading hierarchy, links, code blocks, tables, images, and special characters. For package-level validation, run EPUBCheck:

epubcheck book.epub

Fix missing resources, invalid XHTML, metadata errors, and navigation warnings before distributing the file.