bookdown

Authoring Books and Technical Documents with R Markdown

Yihui Xie

• Publisher: Chapman and Hall/CRC
• Year: 2016
• eBook ISBN: 9781351792592
• Edition: 1
• Topic: Mathematics
• Subtopic: Probability & Statistics
• Index: Mathematics

bookdown: Authoring Books and Technical Documents with R Markdown presents a much easier way to write books and technical publications than traditional tools such as LaTeX and Word. The bookdown package inherits the simplicity of syntax and flexibility for data analysis from R Markdown, and extends R Markdown for technical writing, so that you can make better use of document elements such as figures, tables, equations, theorems, citations, and references. Similar to LaTeX, you can number and cross-reference these elements with bookdown. Your document can even include live examples so readers can interact with them while reading the book. The book can be rendered to multiple output formats, including LaTeX/PDF, HTML, EPUB, and Word, thus making it easy to put your documents online. The style and theme of these output formats can be customized.

We used books and R primarily for examples in this book, but bookdown is not only for books or R. Most features introduced in this book also apply to other types of publications: journal papers, reports, dissertations, course handouts, study notes, and even novels. You do not have to use R, either. Other choices of computing languages include Python, C, C++, SQL, Bash, Stan, JavaScript, and so on, although R is best supported. You can also leave out computing, for example, to write a fiction. This book itself is an example of publishing with bookdown and R Markdown, and its source is fully available on GitHub.

1

Introduction

This book is a guide to authoring books and technical documents with R Markdown (Allaire et al., 2016a) and the R package bookdown (Xie, 2016a). It focuses on the features specific to writing books, long-form articles, or reports, such as:

• how to typeset equations, theorems, figures and tables, and cross-reference them;

• how to generate multiple output formats such as HTML, PDF, and e-books for a single book;

• how to customize the book templates and style different elements in a book;

• editor support (in particular, the RStudio IDE); and

• how to publish a book.

It is not a comprehensive introduction to R Markdown or the knitr package (Xie, 2016c), on top of which bookdown was built. To learn more about R Markdown, please check out the online documentation http://rmarkdown.rstudio.com. For knitr, please see Xie (2015). You do not have to be an expert of the R language (R Core Team, 2016) to read this book, but you are expected to have some basic knowledge about R Markdown and knitr. For beginners, you may get started with the cheatsheets at https://www.rstudio.com/resources/cheatsheets/. The appendix of this book contains brief introductions to these software packages. To be able to customize the book templates and themes, you should be familiar with LaTeX, HTML and CSS.

1.1 Motivation

Markdown is a wonderful language to write relatively simple documents that contain elements like sections, paragraphs, lists, links, and images, etc. Pandoc (http://pandoc.org) has greatly extended the original Markdown syntax,¹ and added quite a few useful new features, such as footnotes, citations, and tables. More importantly, Pandoc makes it possible to generate output documents of a large variety of formats from Markdown, including HTML, LaTeX/PDF, Word, and slides.

There are still a few useful features missing in Pandoc’s Markdown at the moment that are necessary to write a relatively complicated document like a book, such as automatic numbering of figures and tables in the HTML output, cross-references of figures and tables, and fine control of the appearance of figures (e.g., currently it is impossible to specify the alignment of images using the Markdown syntax). These are some of the problems that we have addressed in the bookdown package.

Under the constraint that we want to produce the book in multiple output formats, it is nearly impossible to cover all possible features specific to these diverse output formats. For example, it may be difficult to reinvent a certain complicated LaTeX environment in the HTML output using the (R) Markdown syntax. Our main goal is not to replace everything with Markdown, but to cover most common functionalities required to write a relatively complicated document, and make the syntax of such functionalities consistent across all output formats, so that you only need to learn one thing and it works for all output formats.

Another goal of this project is to make it easy to produce books that look visually pleasant. Some nice existing examples include GitBook (https://www.gitbook.com), Tufte CSS (http://edwardtufte.github.io/tufte-css/), and Tufte-LaTeX (https://tufte-latex.github.io/tufte-latex/). We hope to integrate these themes and styles into bookdown, so authors do not have to dive into the details of how to use a certain LaTeX class or how to configure CSS for HTML output.

1.2 Get started

The easiest way for beginners to get started with writing a book with R Markdown and bookdown is through the demo bookdown-demo on GitHub:

1. Download the GitHub repository https://github.com/rstudio/bookdown-demo as a Zip file,² then unzip it locally.

2. Install the RStudio IDE. Note that you need a version higher than 1.0.0. Please download the latest version³ if your RStudio version is lower than 1.0.0.

3. Install the R package bookdown:

# stable version on CRAN

install.packages("bookdown")

# or development version on GitHub

# devtools::install_github('rstudio/bookdown')

4. Open the bookdown-demo repository you downloaded in RStudio by clicking bookdown-demo.Rproj.

5. Open the R Markdown file index.Rmd and click the button Build Book on the Build tab of RStudio.

Now you should see the index page of this book demo in the RStudio Viewer. You may add or change the R Markdown files, and hit the Knit button again to preview the book. If you prefer not to use RStudio, you may also compile the book through the command line. See the next section for details.

Although you see quite a few files in the bookdown-demo example, most of them are not essential to a book. If you feel overwhelmed by the number of files, you can use this minimal example instead, which is essentially one file index.Rmd: https://github.com/yihui/bookdown-minimal. The bookdown-demo example contains some advanced settings that you may want to learn later, such as how to customize the LaTeX preamble, tweak the CSS, and build the book on GitHub, etc.

1.3 Usage

A typical bookdown book contains multiple chapters, and one chapter lives in one R Markdown file, with the filename extension .Rmd. Each R Markdown file must start immediately with the chapter title using the first-level heading, e.g., # Chapter Title. All R Markdown files must be encoded in UTF-8, especially when they contain multi-byte characters such as Chinese, Japanese, and Korean. Here is an example (the bullets are the filenames, followed by the file content):

• index.Rmd

# Preface {-}

In this book, we will introduce an interesting method.

• 01-intro.Rmd

# Introduction

This chapter is an overview of the methods that we propose to solve an **important problem**.

• 02-literature.Rmd

# Literature

Here is a review of existing methods.

• 03-method.Rmd

# Methods

We describe our methods in this chapter.

• 04-application.Rmd

# Applications

Some _significant_applications are demonstrated in this chapter.

## Example one

## Example two

• 05-summary.Rmd

# Final Words

We have finished a nice book.

By default, bookdown merges all Rmd files by the order of filenames, e.g., 01-intro.Rmd will appear before 02-literature.Rmd. Filenames that start with an underscore _ are skipped. If there exists an Rmd file named index.Rmd, it will always be treated as the first file when merging all Rmd files. The reason for this special treatment is that the HTML file index.html to be generated from inde...

Table of contents

• Cover
• Half Title
• Title Page
• Copyright Page
• Dedication
• Table of Contents
• List of Tables
• List of Figures
• Preface
• About the Author
• 1 Introduction
• 2 Components
• 3 Output Formats
• 4 Customization
• 5 Editing
• 6 Publishing
• Appendix
• Bibliography
• Index