12.4 Output Formats

Thebookdown 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 inbookdown, 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 formatbookdown::gitbook is built uponrmarkdown::html_document, which was explained in Section3.1. The main difference between rendering in R Markdown andbookdown is that a book will generate multiple HTML pages by default. To change the way the HTML pages are split, thesplit_by argument can be specified. This defaults tosplit_by: chapter, but readers may prefer to usesplit_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 ofpdf_book() inbookdown compared topdf_document() inrmarkdown. The primary purpose of the new format is to resolve the labels and cross-references written in the syntax described in Section12.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 withbookdown::epub_book.

12.4.4 A single document

We highlighted in Section12.3 thatbookdown extends the syntax provided by R Markdown, allowing automatic numbering of figures / tables / equations, and cross-referencing them. You may usebookdown within single-file R Markdown documents to benefit from these features. The functionshtml_document2(),tufte_html2(),pdf_document2(),word_document2(),tufte_handout2(), andtufte_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---