Chapter 1 Bookdown basics

This material uses the bookdown package and was built based on ‘A Minimal Book Example’as well a excerpts and concepts from’bookdown: Authoring Books and Technical Documents with R Markdown’, as well as from other available online resources (especially, link).

Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see http://rmarkdown.rstudio.com. When you click the Knit button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document.

The bookdown package can be installed from CRAN or Github:

install.packages("bookdown")
# or the development version
# devtools::install_github("rstudio/bookdown")

1.1 Organization

Subsections can be created using pound signs (#):

# First-level header (only for the title)

## Second-level header

### Third-level header

The default use of the headers will produce numbers. This can be disabled using {-}after the header, e.g., ## Learning objectives {-}.

1.2 Cross-referencing

You can label chapter and section titles using {#label} after them, e.g., we can reference Chapter ?? using \@ref(intro). If you do not manually label them, there will be automatic labels anyway, e.g., we can reference Chapter 1.5 using the name of the chapter: \@(citations).

1.3 Code chunks

R code can be embedded into the books like so:

```{r}
library(palmerpenguins)

penguins[1:2,]
```

Which yields:

library(palmerpenguins)

penguins[1:2,]

##   species    island bill_length_mm bill_depth_mm flipper_length_mm body_mass_g
## 1  Adelie Torgersen           39.1          18.7               181        3750
## 2  Adelie Torgersen           39.5          17.4               186        3800
##      sex year
## 1   male 2007
## 2 female 2007

Please refrain from using multiple # signs when writing annotations inside the code chunks as this could be interpreted by Bookdown as a new header instead of an annotation.

1.3.1 Workshop script

For participants who wish to have the code used during the workshop so that they can easily follow along, we will now automatically create a script using knitr::purl().

purl() will automatically extract the code from all the code chunks used in the book. If you consider that a particular code chunk should not be included in the final script, the purl=FALSE option can be used when creating the chunk. Note that purl=TRUE by default. For example, the following chunk would not be included in the script:

```{r purl=FALSE}
library(palmerpenguins)

penguins[1:2,]
```

Given that purl() will also extract any comments in chunk, it is encourage to annotate the code in the chunks as much as possible so that the script will be detailed for anyone wishing to use it that was not able to attend the workshop.

1.4 Figures and tables

Figures and tables with captions will be placed in figure and table environments, respectively.

par(mar = c(4, 4, .1, .1))

plot(penguins[, c("species", "body_mass_g")])

Figure 1.1: Here is a nice figure!

Reference a figure by its code chunk label with the fig: prefix, e.g., see Figure 1.1 using \@ref(fig:nice-fig). Similarly, you can reference tables generated from knitr::kable(), e.g., see Table 1.1 using \@ref(tab:nice-tab).

knitr::kable(
  head(penguins[ , 1:7], 20), caption = 'Here is a nice table!',
  booktabs = TRUE
)

Table 1.1: Here is a nice table!
species	island	bill_length_mm	bill_depth_mm	flipper_length_mm	body_mass_g	sex
Adelie	Torgersen	39.1	18.7	181	3750	male
Adelie	Torgersen	39.5	17.4	186	3800	female
Adelie	Torgersen	40.3	18.0	195	3250	female
Adelie	Torgersen	NA	NA	NA	NA	NA
Adelie	Torgersen	36.7	19.3	193	3450	female
Adelie	Torgersen	39.3	20.6	190	3650	male
Adelie	Torgersen	38.9	17.8	181	3625	female
Adelie	Torgersen	39.2	19.6	195	4675	male
Adelie	Torgersen	34.1	18.1	193	3475	NA
Adelie	Torgersen	42.0	20.2	190	4250	NA
Adelie	Torgersen	37.8	17.1	186	3300	NA
Adelie	Torgersen	37.8	17.3	180	3700	NA
Adelie	Torgersen	41.1	17.6	182	3200	female
Adelie	Torgersen	38.6	21.2	191	3800	male
Adelie	Torgersen	34.6	21.1	198	4400	male
Adelie	Torgersen	36.6	17.8	185	3700	female
Adelie	Torgersen	38.7	19.0	195	3450	female
Adelie	Torgersen	42.5	20.7	197	4500	male
Adelie	Torgersen	34.4	18.4	184	3325	female
Adelie	Torgersen	46.0	21.5	194	4200	male

1.5 Citations

You can write citations, too. For example, we are using the bookdown package (Xie 2023) in this sample book, which was built on top of R Markdown and knitr (Xie 2015). See Chapter 1.5 for more information on how to make citations.

References

Xie, Yihui. 2015. Dynamic Documents with R and Knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC. https://yihui.org/knitr/.

———. 2023. Bookdown: Authoring Books and Technical Documents with r Markdown. https://CRAN.R-project.org/package=bookdown.