3.1 Primary Reference Resources
Here is a list of resources to learn how to use and edit in bookdown
3 Bookdown Guide
This Resource Guide was created using the bookdown package. bookdown provides a platform to publish references using various output formats (PDF, HTML, Word) and allows for interactivity, insertion of code chunks, and supports a variety of languages (R, Python, Julia, SQL, etc.).
3.2 Install the Bookdown package
The first step to edit and add to this Resource Guide is to install the bookdown package from CRAN or Github. In the RStudio console, run the following:
install.packages("bookdown")
# or the development version
# devtools::install_github('rstudio/bookdown')3.2.1 Additional packages
You may need to install additional packages if you do not currently have them in order to render the Resource Guide bookdown:
downlitformatRherekableExtraRtoolsshinytidyverse
3.2.2 Install TinyTex
TinyTeX is a custom LaTeX distribution. LaTeX, which is pronounced «Lah-tech» or «Lay-tech», is a document preparation system for high-quality typesetting. It is most often used for technical or scientific documents. To learn more about TinyTex, navigate to this document, and to learn more about LaTex, visit the LaTex Project site.
To install TinyTex on your computer, navigate to the R Studio console panel, and type in the following command:
3.3 Render, Build & Publish the Resource Guide
When updates are made to the Resource Guide, it needs to be rendered, built, and then the updates published.
In your Console, type either of these commands depending on which type of render you prefer:
bookdown::render_book("index.Rmd", "bookdown::gitbook")
bookdown::render_book("index.Rmd", "bookdown::pdf_book")
Note: If there is an error during rendering, Google what the error message means! You should be able to find an answer on stack overflow or other tech support site. One of the most common errors during rendering is that not all dependencies (aka packages) have been installed on your local computer.
Figure 3.1: An common error message in the RStudio console: Error in library(here): there is no package called here. If you see this library error message, all you need to do is install the required package! The additional warning messages are notifications that R should be updated to be compatiable with the current packages. These will not hender the render.
Once you have rendered updates using the console commands above:
- navigate to the Environment, Connections, Build, Git panel,
- select the Build tab,
- select Build Bookdown
- once the build is complete (the final line should read
Output created: docs/index/html), commit, pull and push updates to GitHub via the Git tab.
The following information is directly taken from the bookdown package (Xie 2022).
3.4 Formatting
You can use anything that Pandoc’s Markdown supports, e.g., a math equation \(a^2 + b^2 = c^2\).
3.4.1 Referencing Bookdown Chapters
Remember each Rmd file contains one and only one chapter, and a chapter is defined by the first-level heading #.
You can label chapter and section titles using {#label} after them, e.g., reference this Resource Guide Chapter 1 by using the markdown format: \@ref(insert chapter label name here). If you do not manually label them, there will be automatic labels anyway, e.g., Chapter ??.
3.4.2 Formatting Figures
Figures and tables with captions will be placed in figure and table environments, respectively.
Figure 3.2: Here is a nice figure!
Reference a figure by its code chunk label with the fig: prefix, e.g., see Figure 3.2. Similarly, you can reference tables generated from knitr::kable(), e.g., see Table 3.1.
| Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species |
|---|---|---|---|---|
| 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5.0 | 3.6 | 1.4 | 0.2 | setosa |
| 5.4 | 3.9 | 1.7 | 0.4 | setosa |
| 4.6 | 3.4 | 1.4 | 0.3 | setosa |
| 5.0 | 3.4 | 1.5 | 0.2 | setosa |
| 4.4 | 2.9 | 1.4 | 0.2 | setosa |
| 4.9 | 3.1 | 1.5 | 0.1 | setosa |
| 5.4 | 3.7 | 1.5 | 0.2 | setosa |
| 4.8 | 3.4 | 1.6 | 0.2 | setosa |
| 4.8 | 3.0 | 1.4 | 0.1 | setosa |
| 4.3 | 3.0 | 1.1 | 0.1 | setosa |
| 5.8 | 4.0 | 1.2 | 0.2 | setosa |
| 5.7 | 4.4 | 1.5 | 0.4 | setosa |
| 5.4 | 3.9 | 1.3 | 0.4 | setosa |
| 5.1 | 3.5 | 1.4 | 0.3 | setosa |
| 5.7 | 3.8 | 1.7 | 0.3 | setosa |
| 5.1 | 3.8 | 1.5 | 0.3 | setosa |
3.4.3 Citations
You can easily write citations using .bib files within this repository formatted using BibTEX. For example, the bookdown package (Xie 2022) in this reference book, which was built on top of R Markdown and knitr (Xie 2015).
3.4.4 Alt Text for Accessibility
Use the knitr package to add alt text to graphics in R Markdown files
3.4.5 Migrating to Quarto from Bookdown
Love bookdown? Check out Quarto! To learn how to convert bookdown documents to Quarto, check out this blogpost on Openscapes