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 bookdown:::bookdown_skeleton('your-book-dir').

Create a bookdown project in RStudio.

FIGURE 16.5: Create a bookdown project in RStudio.

To demonstrate the usage, we provide a minimal example consisting of three files within the same directory:

  1. directory
  2.   |- index.Rmd
  3.   |- 01-intro.Rmd
  4.   |- 02-analysis.Rmd

Below we show the content of each file and explain their roles.

  • index.Rmd:

    1. ---
    2. title: "A Minimal bookdown Project"
    3. site: bookdown::bookdown_site
    4. output: bookdown::gitbook
    5. ---
    7. # Preface {-}
    9. Some content

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 bookdown::gitbook, bookdown::pdf_book, bookdown::word_document2, and bookdown::epub_book.

The next two Rmd files are two chapters:

  • 01-intro.Rmd:

    1. # Chapter 1
    3. This is chapter 1.

  • 02-analysis.Rmd:

    1. # Chapter 2
    3. This is chapter 2.

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).

References

———. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://github.com/rstudio/bookdown.

———. 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.