Why?

This is the second post about working with Bookdown and my experience on the process (first post is here). This post focuses on how I found that was easy to compartmentalize my work and some tips I learned along the way (I will probably write about some other things in the future as well).

Use “chapters”

When I started working with Bookdown I was making a single document for my manuscript. Doing it in that way was manageable at the beginning, but as I wrote more and added more code, scrolling down started to become painful (specially after I realized one day that I was at about 1000 lines in length between code/text). I decided that I wanted to break the document in pieces, but I didn’t know how. Reading through the Web I came to realize that you can piece a Bookdown document using the child option (see here for a thorough description). The child option means that you will break your document in “Chapters” but they will be knitted in a single document when you compile the PDF/HTML output. For this to work you need in the same working directory:

• A “central” document that will contain the YAML header and the instructions to call all the other documents.
• All your “chapters”

The “central” document will contain all the formatting instructions (YAML header with bibliography, references styles, \(\LaTeX\) options, etc) and chunks of code where you call the “chapters”. Suppose you call this “central” document Main.Rmd, and that you have in the same directory two “chapters”: Chapter 1.Rmd and Chapter 2.Rmd.

In Main.Rmd, after they YAML header and the chunk where the knitr options are specified, you need to add the chunks that will call the chapters, like this:

```{r child='Chapter 1.Rmd'} 
```

```{r child='Chapter 2.Rmd'} 
```

The very convenient thing about using this approach, is that you can move across the chapters and find things way more quickly than using a single document; you can also check bugs in your code without constantly scrolling up and down. Keep in mind that all your packages need to be loaded in Main.Rmd, the “chapters” do not have a YAML header or an R chunk for options, you can start them just with text. If you were to open the file for the first chapter it would look like this:

• Chapter 1.Rmd

# Chapter 1: Introduction

In this section we will review the current status of the field of interest.