Rpub – an ePub generator in Ruby

Introduction

Rpub is a command-line tool that generates a collection of plain text input files into an eBook in ePub format. It provides several related functions to make working with ePub files a little easier:

Generation of table of contents
Packaging your eBook in an archive with additional README file
Embedding fonts
Easy previewing as you write
.mobi compatibility

Installation

Rpub is distributed as a Ruby gem, which should be installed on most Macs and Linux systems. Once you have ensured you have a working installation of Ruby and Ruby gems, install the gem as follows from the command line:

$ gem install rpub

You can verify the gem has installed correctly by checking its version number:

$ rpub -v

If this generates an error, something has gone wrong. You should see something along the lines of rpub 1.0.0.

Usage

Basics

ePubs are basically collections of HTML files, combined in a single archive according to a set of predefined rules. Rpub generates these files for you from simple text files written in Markdown, a very readable markup language created by John Gruber. This very README file is an example of a Markdown document.

The idea is you write several Markdown files using your favourite text editor, and save them as plain text in your project directory. Usually you would write one file per chapter. By invoking the rpub program you convert those files to HTML and combine them in an ePub archive:

$ rpub compile
Generating my-new-book-0.1.0.epub... Done!

After you have run the rpub compile command, you will find a new .epub file in your project directory. The name of this file depends on the title of your book, and its version number. You can set these values, as well as a few others, in a special configuration file called config.yml:

---
author: Your Name
title: My new book
version: 0.1.0

This file is written in YAML and sets basic properties of your book project.

Since regenerating your ePub file and opening it in a suitable reader application is cumbersome, Rpub can generate a simple preview document for you:

$ rpub preview

This will generate a new HTML file in your project directory with a name similar to your ePub file. This is the entire text of your book as a single web page for easy viewing in any browser.

Generating a .mobi file

Since the ePub and Mobipocket file formats are very (very) similar it is quite easy to create a .mobi version of your book, suitable for reading on Amazon’s Kindle. To do so, you will need to install the kindlegen program Amazon provides.

Here’s how it works:

Install kindlegen (download it here)
Compile your book as usual using rpub compile
Compile my-book.epub to my-book.mobi: kindlegen my-book.epub.

Optionally, include your my-book.mobi in your package by adding it to your list of packaged files (see “Packaging for distribution”).

Advanced features

Packaging for distribution

Often you want to distribute your ebook over the internet, along with some extra files. You’ll probably want to include a README file, a license or references to extra online resources. A package task is defined to generate a single compressed archive file from your generated ebook along with such additional files.

You list the files to include with your ebook in your config.yml file, along with the resulting packaged file name:

---
package_file: mybook.zip
package:
  - README
  - license.txt
  - code-samples.rb

All the filenames listed under package are looked up in the root of your project directory. These files will be combined with the ebook in the mybook.zip file in your project directory.

Automatic table of contents

Rpub automatically generates a table of contents for you, if you want it to. It does this by scanning all your markdown files for headings and listing them on a single page in the ebook. Each entry in the table of contents is linked to its appropriate heading in the chapter, and has various hooks for your stylesheet to determine its formatting.

To enable the automatic generation of a table of contents, add the following configuration to your config.yml file:

toc: true

Note that this only affects the human-readable table of contents, represented as a page in your book. Rpub will alway generate the .epub table of contents for you, which contains the machine-readable references to your chapters. It will, by default, reference all chapter titles and subheadings for you, but you can customize the number of levels that will be included using the following in your config.yml file:

max_level: 3

Custom layout and styles

When you compile a set of Markdown files to an ePub file, rpub uses a default HTML layout and set of styles to determine the look and feel of the book. These will do fine for most cases, but you can provide your own, if you are so inclined.

Simply define a layout.html and/or styles.css in your project directory. Your HTML file will be parsed with Erb, an so you can include your writing using the @body instance variable:

<html>
<body>
  <%= @body %>
</body>
</html>

Note 1: this feature is actually provided by the Kramdown gem, so have a look at the standard Kramdown document template to see some nifty tricks.

Note 2: despite the name ‘html’ and .html extension, your file actually has to be XHTML-compliant.

You can also provide custom layouts or styles to use when invoking the compile or preview commands, using the -l or -s options:

$ rpub compile -l /tmp/my-layout.html

If you like the default layout or styles, but want to adapt them, you can copy those files into your project using the generate subcommand:

$ rpub generate

Command reference

rpub compile: generate .epub file
rpub package: create zip file with compiled book and other listed files
rpub preview: generate preview HTML file
rpub generate: copy default layout.html, styles.css and config.yml
rpub help: get help on subcommands
rpub clean: remove generated files

Configuration reference

title: the book title (string)
descrption: one-line summary of the book (string)
creator: author name (string)
publisher: publisher name (string)
subject: book subject/category (string)
language: language code of the book contents, e.g. ‘en’ (string)
rights: copyright line (string)
version: version number of the book to include in the .epub filename (string)
toc: whether to generate a table of contents as book page (boolean, default false)
max_level: the maximum depth of the .epub table of contents (number, default 2)
ignore: list of files not to include in the epub, that otherwise would (array)
package: list of files to be included in the archive created by the package task (array)

Examples

See the examples directory for two example projects.

Documentation

See the inline API docs for more information.

Other

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don’t break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.

Issues

Please report any issues, defects or suggestions in the Github issue tracker.

What has changed?

See the HISTORY file for a detailed changelog.

Credits

Created by: Arjan van der Gaag
URL: http://arjanvandergaag.nl
Project homepage: http://avdgaag.github.com/rpub
Date: april 2012
License: MIT-license (same as Ruby)