Skip to main content

bookdown Authoring Books and Technical Documents with R Markdown

Yihui Xie

Section 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.
🔗

Subsection 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().
🔗
bookdown::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", "epub2"), md_extensions = NULL,
  global_numbering = !number_sections, 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.
    🔗
    🔗
  • 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.
    🔗
    🔗
  • 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, and so on. Figure/table captions, cross-references, custom blocks, and citations mentioned in Chapter 2 also work for EPUB.
🔗
There are several EPUB readers available, including Calibre, Apple’s iBooks, and Google Play Books.
🔗
🔗

Subsection 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.
🔗
🔗
🔗
PrevTopNext