EPUB Tools

TL;DR: A Ruby gem and CLI for working with EPUB files: extract, split, initialize, add chapters, pack, unpack, compile, and append to EPUB books.

Installation

Requirements

Ruby 3.2 or higher

Install from RubyGems

gem install epub_tools

Build and install locally

bundle install
gem build epub_tools.gemspec
gem install ./epub_tools-*.gem

CLI Usage

After installation, use the epub-tools executable:

Usage: epub-tools COMMAND [options]

Commands:

init Initialize a new EPUB directory structure
extract Extract XHTML files from EPUB archives
split Split an XHTML file into separate chapter files
add Add chapter XHTML files into an existing EPUB
pack Package an EPUB directory into a .epub file
unpack Unpack a .epub file into a directory
compile Takes EPUBs in a dir and splits, cleans, and compiles into a single EPUB
append Extracts and splits EPUBs from a dir and appends them to an existing EPUB

Run epub-tools COMMAND --help for details on options.

Example

# Extract XHTMLs
epub-tools extract -s source_epubs -t xhtml_output

# Split chapters
epub-tools split -i xhtml_output/chapter1.xhtml -t "My Book" -o chapters

# Initialize EPUB
epub-tools init -t "My Book" -a "Author Name" -o epub_dir -c cover.jpg

# Add chapters to EPUB
epub-tools add -c chapters -e epub_dir/OEBPS

# Package EPUB (Ruby)
epub-tools pack -i epub_dir -o MyBook.epub

# Unpack EPUB
epub-tools unpack -i MyBook.epub -o unpacked_dir

# Full compile workflow: extract, split, initialize, add, and pack into one EPUB
epub-tools compile -t "My Book" -a "Author Name" -s source_epubs -c cover.jpg -o MyBook.epub

# Append chapters from new EPUBs to an existing book
epub-tools append -s new_epubs -t MyBook.epub

Library Usage

Use the library directly in Ruby:

require 'epub_tools'

# Full compile workflow: extract, split, and compile into a new EPUB
EpubTools::CompileBook.new(
  title: 'My Book', author: 'Author Name',
  source_dir: 'source_epubs', cover_image: 'cover.jpg',
  output_file: 'MyBook.epub'
).run

# Append chapters from new EPUBs to an existing book
EpubTools::AppendBook.new(
  source_dir: 'new_epubs',
  target_epub: 'MyBook.epub'
).run

# Individual steps can also be used standalone:

# Extract XHTML files from EPUBs
EpubTools::XHTMLExtractor.new(
  source_dir: 'source_epubs', target_dir: 'xhtml_output'
).run

# Split a multi-chapter XHTML into individual chapter files
EpubTools::SplitChapters.new(
  input_file: 'xhtml_output/chapter1.xhtml', book_title: 'My Book',
  output_dir: 'chapters', output_prefix: 'chapter'
).run

# Initialize a new EPUB directory structure
EpubTools::EpubInitializer.new(
  title: 'My Book', author: 'Author Name',
  destination: 'epub_dir', cover_image: 'cover.jpg'
).run

# Add chapter files into an EPUB
EpubTools::AddChapters.new(
  chapters_dir: 'chapters', oebps_dir: 'epub_dir/OEBPS'
).run

# Package an EPUB directory into a .epub file
EpubTools::PackEbook.new(input_dir: 'epub_dir', output_file: 'MyBook.epub').run

# Unpack a .epub file into a directory
EpubTools::UnpackEbook.new(epub_file: 'MyBook.epub', output_dir: 'unpacked_dir').run

Development & Testing

Clone the repo and install dependencies:

git clone https://github.com/jaimerodas/epub_tools.git
cd epub_tools
bundle install

Run tests:

bundle exec rake test

Run linting (RuboCop):

bundle exec rubocop

Documentation

Detailed API documentation can be generated using YARD. To view the docs locally, serve the documentation locally with YARD:

bundle exec yard server --reload

Then navigate to http://localhost:8808 in your browser.

To (re)generate the documentation, install the documentation dependencies and run:

bundle install --with doc
bundle exec yard doc

Contributing

Pull requests welcome! Please open an issue for major changes.

epub_tools

Runtime