= crystal-asciidoctor-epub3 :toc: left :toclevels: 2

AsciiDoc to EPUB3 converter for Crystal, equivalent of the https://github.com/asciidoctor/asciidoctor-epub3[asciidoctor-epub3] Ruby gem.

link:README.fr.adoc[Version française]

== Features

• Converts AsciiDoc documents to valid EPUB3 files
• Sections, paragraphs, lists (ordered/unordered/description), tables
• Code blocks with syntax highlighting (via crystal-rouge), admonitions, blockquotes, verses, sidebars
• Images embedded in EPUB ZIP, thematic breaks
• Cover page from :front-cover-image: attribute
• Footnotes with back-links
• Hierarchical table of contents (nested sections)
• Table of contents (NCX + EPUB3 NAV)
• PDF bookmarks equivalent (NCX navigation)
• Metadata: title, author, language, description, publisher
• Cover image support
• Default stylesheet included
• Library API for use in web applications
• CLI for command-line usage

== Installation

=== As a library

Add to your shard.yml:

[source,yaml]

dependencies: crystal-asciidoctor-epub3: github: aloli-crystal/crystal-asciidoctor-epub3 version: "~> 2.3"

Then run shards install.

=== CLI binary

[source,bash]

git clone https://github.com/aloli-crystal/crystal-asciidoctor-epub3.git cd crystal-asciidoctor-epub3 shards build --release sudo cp bin/crystal-asciidoctor-epub3 /usr/local/bin/

== Usage

=== Library API

[source,crystal]

require "asciidoctor_epub"

input = <<-ADOC = My Book Author Name :lang: en

== Chapter 1

This is the first chapter with bold and italic.

== Chapter 2

A code example:

[source,crystal] ---- puts "Hello!" ---- ADOC

doc = Asciidoctor.load(input)

Get EPUB as bytes (for web applications)

bytes = AsciidoctorEpub::Converter.new.convert(doc)

Or write directly to file

AsciidoctorEpub::Converter.new.convert_to_file(doc, "my-book.epub")

=== In a Kemal web application

[source,crystal]

require "kemal" require "asciidoctor_epub"

post "/generate-epub" do |env| content = env.params.body["content"] doc = Asciidoctor.load(content) epub_bytes = AsciidoctorEpub::Converter.new.convert(doc)

env.response.content_type = "application/epub+zip" env.response.headers["Content-Disposition"] = "attachment; filename=document.epub" env.response.write(epub_bytes) end

Kemal.run

=== Command line

[source,bash]

crystal-asciidoctor-epub3 document.adoc

=> Generates document.epub

---

Options:

[cols="1,3"] |=== | Option | Description

| -o FILE, --out-file FILE | Output EPUB file (default: <input>.epub)

| --sample | Generate reference document (reference.adoc + reference.adoc.epub)

| -v, --version | Show version

| -h, --help | Show help |===

=== Reference document

The --sample option generates a comprehensive AsciiDoc document and its EPUB, covering all AsciiDoc elements (formatting, lists, tables, code, admonitions, formulas, diagrams, etc.):

[source,bash]

crystal-asciidoctor-epub3 --sample

→ reference.adoc + reference.adoc.epub

---

This document serves as a conformance test for validating EPUB rendering.

== Versions

[cols="2,2,2"] |=== | | Version | Date

| Ruby asciidoctor-epub3 (reference) | 2.3.0 | 2025-08-31

| Ruby asciidoctor (parser, via crystal-asciidoctor) | 2.0.26 | 2025-10-24

| crystal-asciidoctor-epub3 | 2.3.0 | 2026-04-09 |===

== Development

[source,bash]

git clone https://github.com/aloli-crystal/crystal-asciidoctor.git git clone https://github.com/aloli-crystal/crystal-asciidoctor-epub3.git cd crystal-asciidoctor-epub3 shards install crystal spec

== License

MIT