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
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
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
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
--- 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
Here's how it works:
kindlegen(download it here)
- Compile your book as usual using
Optionally, include your
my-book.mobi in your package by adding it to your
list of packaged files (see "Packaging for distribution").
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
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
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
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
styles.css in your project directory.
Your HTML file will be parsed with Erb, an so you can include your writing
@body instance variable:
<html> <body> <%= @body %> </body> </html>
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
preview commands, using the
$ 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
$ rpub generate
: generate .epub file
: create zip file with compiled book and other listed files
: generate preview HTML file
: copy default layout.html, styles.css and config.yml
: get help on subcommands
: remove generated files
: the book title (string)
: one-line summary of the book (string)
: author name (string)
: publisher name (string)
: book subject/category (string)
: language code of the book contents, e.g. 'en' (string)
: copyright line (string)
: version number of the book to include in the .epub filename (string)
: whether to generate a table of contents as book page (boolean, default false)
: the maximum depth of the .epub table of contents (number, default 2)
: list of files not to include in the epub, that otherwise would (array)
: list of files to be included in the archive created by the package task (array)
See the examples directory for two example projects.
See the inline API docs for more information.
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.
Please report any issues, defects or suggestions in the Github issue tracker.
What has changed?
See the HISTORY file for a detailed changelog.