Learning R Markdown and {bookdown}

The first place to start to learn {bookdown} is Yihui Xie’s bookdown: Authoring Books and Technical Documents with R Markdown. In addition to going into {bookdown}, it provides some information on R Markdown and how to use it as well.

If you are new to R Markdown, Yihui, J. J. Allaire, and Garrett Grolemund wrote a definitive guide, available here.

These books offer great guidance on {bookdown} and R Markdown, but below are some details if you want to get started with a minimal example of a bookdown.

---
title: "Test Book"
author: "Me"
site: bookdown::bookdown_site
output: bookdown::gitbook
---

# Welcome {-}

book_filename: "bookdown-demo"
delete_merged_file: true
new_session: yes

bookdown::gitbook

bookdown::serve_book()

Snooping on others’ GitHub files

When I do not know how to do something in R, I look at people who I want to emulate and snoop on their GitHub repository pages. It is so incredibly handy (and wonderful) that others post their code for all to see.

This is how we learned just how to even start using bookdown (copying people’s files, seeing what happened when we ran them), but also the creative ways that others went about customizing their books.

While there’s an archive of many books using {bookdown}, here are some specific works we used during our bookdown development:

• Forecasting: Principles and Practice by Rob J Hyndman and George Athanasopoulos (book, repo) for customizing CSS on a bookdown with custom fonts, colors, etc.
• Geocomputation with R by Robin Lovelace, Jakub Nowosad, and Jannes Muenchow (book, repo) to learn how to give figures labels.

We highly recommend seeing what others have done in the past and trying things out so your book reflects what you would like it to look like!

.book .book-summary ul.summary li a:hover {
  background-color: #ffffff;
  color: #ffbc49;
}

Caching code chunks

As mentioned in Yihui’s book, you can cache certain code chunks so they do not have to rerun each time you render the book. We found this very handy, as some complex models took some time to run.

Important to note though: if you use set.seed, you will need to include it in every code chunk; setting it in only one code chunk will not mean it is set for all code chunks.

Figuring out your publisher’s requirements

Creating a book using R/R Studio/{bookdown} is great because all of these tools are so versatile and we were able to use each one to meet our publisher requirements, minimize manual work, and reduce redundancies.

For example, here’s how {bookdown} helped us do what we had to do:

• Our manuscript had to be in Word: we were able to render the bookdown using Word.
• Our manuscript needed all tables and figures to be labeled: we were able to automate this using the .yml files.
• Our figures had to be of a certain size and dimension: we were also able to automate this using the .yml files.
• We needed to send all of our figures separately from the manuscript: they are all saved separately due to the rendering function of {bookdown}.
• We needed a bibliography: we were able to create a bibliography of works and packages, all automated with {bookdown}.

Because of R:

• All tables had to be in Word format: at the time, we hadn’t seen this from {gtsummary}, and we spent quite a bit of time trying to use {gt} for our tables before realizing that we wouldn’t be able to output using Word. We then switched to {sjPlot}, which got us exactly what we needed.

• Our bibliography had to be in APA format: thanks to a file that Josh had (saved here), all we had to do was save that file and add biblio-style: "apalike" to our index.Rmd file for everything to show up in the format we needed.

And, thanks to R Studio:

• We were able to spell-check files within the IDE!
• We used its handy search function to create the index.

So, we recommend gathering all of your publisher’s requirements and then mapping them to the different tools at your disposal. This saves a lot of time and headache when it’s finally time to send over the final manuscript.

Determining how to collaborate

Since my co-authors and I all knew GitHub, we decided to use GitHub to write the book. This was great because it was a transparent way of writing the book (non-authors added issues and contributed as they saw fit). We were able to go back in time if needed to fix errors or see what had been changed.

We had to decide how updating the book would work. Ultimately, we decided that one person would be in charge of rendering the book – this helped reduce any code conflicts. However, there may be other ways of working that would be better for you.

Conclusion

In conclusion, we chose to use {bookdown} to create a book manuscript because we wanted to be transparent in our work, leverage R and its many tools, and be as efficient as possible when writing a book across five people. Despite some technical lift (and a lot of trial and error), it eventually resulted in a smooth workflow for our group. Thanks to the many resources and code available out there, we were able to learn {bookdown} as we wrote. Thanks to {bookdown}, we output the final manuscript that resulted in our book!