ePubber – generating ePub files with Ruby

ePub is a digital book format which is pretty common nowadays. It’s supported natively by Windows and Android and it’s one of the official formats for digital books in the Apple Books store.

In this post I’ll talk about generating ePub files with Ruby and how to painlessly integrate this feature to your application. I’ll be using a Ruby gem I created called ePubber, which I created to help manage ePub content.

What is an ePub file made of?

An ePub is basically a bunch of HTML files zipped together. What makes this format great is that you can use CSS, images, vectors, and if you are a web developer, there’s nothing you need to learn, just a few conventions of which files do what and where to put them.

Note that one feature of ePub is digital rights management, which is not currently supported in the Ruby gem we’ll use.

Let’s write a book

This is easier that you might have expected. First, add epubber as a dependency in your Ruby project:
gem 'epubber'
Then
$ bundle
Or install on it’s own:
$ gem install epubber

Now to generate a book, there are a few things we’ll need, namely: a title, an author, an URL, and a chapter.

require 'epubber'
path = Epubber.generate do |book|
  book.title 'ePub demo book'
  book.author 'Ramirez, Federico'
  book.url 'https://beezwax.net'
  book.chapter do |chapter|
    chapter.title 'Chapter 1'
    chapter.content '<p>This is some content!</p>'
  end
end

Now if you run that file, it will generate a new book and save the path in the path variable. By default, the path will look something like /tmp/ePub demo book.epub.

If you open that file with an ePub reader (iBooks in macOS and Edge in Windows) you will see our little chapter there.

Congratulations! You did it! It wasn’t that hard, was it?

Chapters, Cover, Intro, ToC

Now, most likely you’ll want more than a single chapter for your book. ePubber allows you to define a few more things, like a cover and introduction. It will also take care of the building the Table of Contents for you, so no worries about that one.

This is what a more complete example looks like:

require "epubber"
current_dir = File.dirname(__FILE__)
cover_image = File.new "#{current_dir}/cover.jpg"
path = Epubber.generate(working_dir: current_dir) do |b|
  b.title "My First EPUB book"
  b.author "Ramirez, Federico"
  b.url "https://beezwax.net"
  b.cover do |c|
    c.file cover_image
  end
  b.introduction do |i|
    i.content "<p>This is an introduction.</p>"
  end
  b.chapter do |c|
    c.title "Chapter 1"
    c.content "<p>This is some content!</p>"
  end
  b.chapter do |c|
    c.title "Chapter 2"
    c.content "<p>Some more content this is.</p>"
  end
end
puts "Book generated in #{path}"

That will generate a book in the same directory of the Ruby script being run. If you want to play with it yourself, check out ePubber-demo on GitHub.

Conclusion

While exporting ePub files might not be a common task, sometimes it’s just the best option. Creative writing websites are a great example, allowing authors to export digital books on-demand is a great feature, and it can be the feature that gives you an edge over the competition.

I hope this post helps you learn how easy it is to export ePub files, as well as give you another tool for your toolbox, so you can use it when the time is right 🙂

Cheers!
— Fede