Appendix B: R Markdown and Bookdown

This book is built using R Markdown and bookdown methods, and published at http://bookdown.org. There are some great resources on both of these at Xie, Allaire, and Grolemund (2019) and Xie (2021), but I thought it might be useful to provide some things I’ve discovered.

R Markdown

Markdown isn’t new and isn’t at all restricted to R. It’s the basis for Jupyter Notebooks, which I tend to use for Python but also works with R (the “py” in Jupyter is for Python and the “r” is for R); but I think R Markdown is better developed within RStudio, which provides more of an all-in-one integrated development environment (IDE).

For most users, what’s covered in the cheat sheet, which should be at https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf is all you need to be able to format nice R Markdown documents, but the more thorough treatment at Xie, Allaire, and Grolemund (2019) is a good resource for going further.

Bookdown

While you can build a nice looking document in R Markdown, there are some other things that are useful for building a larger book out of it, like handling chapters and references, so you’ll want to review Xie (2021) to learn more. Some notes on building a book at github and bookdown.org:

  • The book is built in RStudio and all Markdown and other files hosted in a GitHub repository. You’ll need to learn more about that.
  • Normally, html is the output format (and a variation on this is gitbook). To also create pdf you need to also specify it in the _output.yml file like I’ve done for this book:
bookdown::gitbook:
  css: style.css
  config:
    toc:
      before: |
        <li><a href="./">Environmental Data Science</a></li>
      after: |
        <li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
    book_filename: "envdatasci"
  toc_depth: 4
bookdown::pdf_book:
  keep_tex: TRUE

  • To create pdf however you need latex, so install.packages(“tinytex”), then in the project: tinytex::install_tinytex() to create the requisite files. See https://yihui.org/tinytex/

  • Use the Build menu in RStudio to specify whether you want to build which type you’ve specified in the _output.yml file. Since building a long book like this one can take a long time (about 35 minutes for both html and pdf for this book), I sometimes just build the HTML version, then build the pdf separately if it works, and since most people will use the HTML version I update that more frequently.

  • Note that pdfs don’t include interactive maps except as a static rendering.

  • It’s useful to list all of your chapters in order with the _bookdown.yml file. For example this book includes the following in that file.

rmd_files: ["index.Rmd", "introduction.Rmd", "abstraction.Rmd", "visualization.Rmd", "transformation.Rmd",
            "spatialDataMaps.Rmd", "spatialAnalysis.Rmd", "spatialRaster.Rmd",
            "statistics.Rmd", "modeling.Rmd", "ImageClassification.Rmd",
            "TimeSeries.Rmd",  "communication.Rmd",
            "AppendixPackage.Rmd", "AppendixRMarkdownBookdown.Rmd", "references.Rmd"]
  • Learn how to organize the book with chapters set aside by # in markdown then subheadings at various levels using ##,, ###, etc., and don’t forget the space after the last hash.
  • The automatic numbering of chapters and subheadings is useful, but if you want a section to not use numbering, like this appendix, including {-} at the end of the every section header line.
  • Creating sections, like Spatial, is done by including `(PART) before the section name, like the following, which starts off the section with this special heading followed by the first chapter:
# (PART) Spatial {-}

# Spatial Data and Maps

Note that the section is excluded from the automatic numbering with {-}.

I guess I could have included some text to introduce the section but the above works to include the section name in the table of contents.

Display options in code chunks

The display options for code chunk headers {r …} are very important to figure out in order to avoid unwanted messages in the book. Each option is separated by a comma. See https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf for a list of these options. For instance:

  • To display the results of code without providing the code, which I sometimes use for exercises to show the goal, use echo=F. is another approach. for code with output we want to see, separate from the above to see the output, otherwise excluded by include=F.
  • Sometimes warnings aren’t desired, so warning = F is handy; however you might want to wait until you’ve confirmed that the warnings aren’t telling you something important.
  • message = F occasionally works, but some things that seem like messages are actually results, for instance:
  • st_read will create unwanted messages that are actually results, so you can either put it in a code chunk that isn’t displayed at all with include=F or probably better use results = "hide". For instance, the following code is in a code chunk that has three options {r warning=F, results="hide", message=F} to avoid printing quite a lot of unwanted stuff:
library(sf); library(igisci)
places <- st_read(ex("sierra/CA_places.shp"))

References

Xie, Yihui. 2021. Bookdown: Authoring Books and Technical Documents with r Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/bookdown/.
Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2019. R Markdown: The Definitive Guide. 1st ed. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown/.