3.3 E-Books

Currently bookdown provides two e-book formats, EPUB and MOBI. Books in these formats can be read on devices like smartphones, tablets, or special e-readers such as Kindle.

3.3.1 EPUB

To create an EPUB book, you can use the epub_book() format. It has some options in common with rmarkdown::html_document():

epub_book(fig_width = 5, fig_height = 4, dev = "png",
  fig_caption = TRUE, number_sections = TRUE,
  toc = FALSE, toc_depth = 3, stylesheet = NULL,
  cover_image = NULL, metadata = NULL,
  chapter_level = 1, epub_version = c("epub3", "epub"),
  md_extensions = NULL, pandoc_args = NULL,
  template = "default")

The option toc is turned off because the e-book reader can often figure out a TOC automatically from the book, so it is not necessary to add a few pages for the TOC. There are a few options specific to EPUB:

  • stylesheet: It is similar to the css option in HTML output formats, and you can customize the appearance of elements using CSS.
  • cover_image: The path to the cover image of the book.
  • metadata: The path to an XML file for the metadata of the book (see Pandoc documentation for more details).
  • chapter_level: Internally an EPUB book is a series of “chapter” files, and this option determines the level by which the book is split into these files. This is similar to the split_by argument of HTML output formats we mentioned in Section 3.1, but an EPUB book is a single file, and you will not see these “chapter” files directly. The default level is the first level, and if you set it to 2, it means the book will be organized by section files internally, which may allow the reader to load the book more quickly.
  • epub_version: Version 3 or 2 of EPUB.

An EPUB book is essentially a collection of HTML pages, e.g., you can apply CSS rules to its elements, embed images, insert math expressions (because MathML is partially supported), and so on. Figure/table captions, cross-references, custom blocks, and citations mentioned in Chapter 2 also work for EPUB. You may compare the EPUB output of this book to the HTML output, and you will see that the only major difference is the visual appearance.

There are several EPUB readers available, including Calibre (https://www.calibre-ebook.com), Apple’s iBooks, and Google Play Books.

3.3.2 MOBI

MOBI e-books can be read on Amazon’s Kindle devices. Pandoc does not support MOBI output natively, but you may use third-party tools to convert EPUB to MOBI. One possible tool is Calibre. Calibre is open-source and free, and supports conversion among many more formats. For example, you can convert HTML to EPUB, Word documents to MOBI, and so on. The function calibre() in bookdown is a wrapper function of the command-line utility ebook-convert in Calibre. You need to make sure that the executable ebook-convert can be found via the environment variable PATH. If you use macOS, you can install Calibre with Homebrew (https://brew.sh) via the command brew cask install calibre, so you do not need to worry about the PATH issue.