16.9 Write books and long-form reports with bookdown
The bookdown package (Xie 2020c) is designed for creating long-form documents that are composed of multiple R Markdown documents. For example, if you want to write a book, you can write each chapter in its own Rmd file, and use bookdown to compile these Rmd files into a book.
For RStudio users, the easiest way to get started is to create a bookdown project with the IDE by selecting
File -> New Project -> New Directory -> Book Project using bookdown, as you can see from Figure 16.5.
If you do not use RStudio or if you prefer to work from the console, you may produce the same result by calling the function
To demonstrate the usage, we provide a minimal example consisting of three files within the same directory:
Below we show the content of each file and explain their roles.
The first file is typically called
index.Rmd. It should be the only Rmd file in which you provide the YAML frontmatter. It should also include a special YAML field
site: bookdown::bookdown_site, so that rmarkdown knows to use bookdown to build all Rmd files, instead of rendering a single Rmd file. You can use any bookdown output formats, such as
The next two Rmd files are two chapters:
To render these Rmd files, you should call
bookdown::render_book('index.Rmd') instead of
rmarkdown::render(). Under the hood, bookdown merges all Rmd files into a single Rmd by default and compiles it. Files are merged in alphabetical order. That is why we added numeric prefixes to filenames in the above example.
There are a lot of settings that you can customize for a bookdown project. For a more comprehensive overview of bookdown, you may see Chapter 18 the rmarkdown book (Xie, Allaire, and Grolemund 2018). For the full documentation, see the bookdown book (Xie 2016).
Xie, Yihui. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://github.com/rstudio/bookdown.
Xie, Yihui. 2020c. Bookdown: Authoring Books and Technical Documents with R Markdown. https://github.com/rstudio/bookdown.
Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.