12.4 Output Formats

The bookdown package includes the following output formats:

• HTML:
  • gitbook
  • html_book
  • tufte_html_book
• PDF:
  • pdf_book
• e-book:
  • epub_book
• Single documents:
  • html_document2
  • tufte_html2
  • pdf_document2
  • tufte_handout2
  • tufte_book2
  • word_document2

12.4.1 HTML

Although multiple formats are available for HTML books in bookdown, we will focus on the Gitbook style, which appears to be the most popular format. It provides a clean style, with a table of contents on the left. The design is fully responsive to make the content suitable for both mobile and desktop devices.

The output format bookdown::gitbook is built upon rmarkdown::html_document, which was explained in Section 3.1. The main difference between rendering in R Markdown and bookdown is that a book will generate multiple HTML pages by default. To change the way the HTML pages are split, the split_by argument can be specified. This defaults to split_by: chapter, but readers may prefer to use split_by: section if there are many sections within chapters, in which case a chapter page may be too long.

12.4.2 LaTeX/PDF

There are limited differences between the output of pdf_book() in bookdown compared to pdf_document() in rmarkdown. The primary purpose of the new format is to resolve the labels and cross-references written in the syntax described in Section 12.3.5.

Pandoc supports LaTeX commands in Markdown. Therefore if the only output format that you want for a book is LaTeX/PDF, you may use the syntax specific to LaTeX, such as \newpage to force a page break. A major disadvantage of this approach is that LaTeX syntax is not portable to other output formats, meaning that these changes will not be transferred to the HTML or e-book outputs.

12.4.3 E-books

The e-book formats can be read on devices like smartphones, tablets, or special e-readers such as Kindle. You can create an e-book of the EPUB format with bookdown::epub_book.

12.4.4 A single document

We highlighted in Section 12.3 that bookdown extends the syntax provided by R Markdown, allowing automatic numbering of figures / tables / equations, and cross-referencing them. You may use bookdown within single-file R Markdown documents to benefit from these features. The functions html_document2(), tufte_html2(), pdf_document2(), word_document2(), tufte_handout2(), and tufte_book2() are designed for this purpose. To use this in a traditional R Markdown document, you can replace the output YAML option as follows:

---
title: "Document Title"
output: bookdown::pdf_document2
---