Creating a book with bookdown in R - Part 2: Chapters and References

Introduction

Previously, we learned how to start a bookdown project (Part 1). We installed bookdown and created an e-book project. We also rendered the project by using the Build feature in R Studio.

In this tutorial, we will go over how to create chapters and add references/citations for an e-book using bookdown. Chapters (also sections) are based on separate rmd files, and references/citations are saved in the *.bib file in the e-book project folder. This tutorial will provide a high-level overview on how to leverage these features to create chapters and references/citations for your e-book.

This is the second tutorial on how to create and maintain an e-book using bookdown; I plan on writing several more on this subject.

Chapter structure

We can create chapters in a bookdown project with several rmd files.

Let’s take a look at a directory of chapters for a example bookdown project:

directory:
  -- index.rmd
  -- 01-chap01.rmd
  -- 02-chap02.rmd
  -- 03-references.rmd

In this example, we have four chapters ( index, 01-chap01, 02-chap02, and 03-references). Each of these chapters are rmd files that were created beforehand using R Markdown.

These chapters are located within the same directory as your bookdown project folder. For this tutorial, I have provided these files on my GitHub site.

Bookdown project file directory

However, we have to be careful with how we name the rmd files because this will affect the order. In bookdown, the first chapter is the index.rmd file. I don’t start my “actual” Chapter 1 with the index.rmd file. I usually reserve the index.rmd file as my Prelude or Introduction chapter (e.g., “Chapter 0”). Hence, I don’t label the index.rmd file with the 01 prefix. I reserve this for the “actual” Chapter 1. In bookdown, the index.rmd file will be labeled as “Chapter 1” unless you add {-} to the main header in the index.rmd file. See example below:

Making the index.rmd file not contain the Chapter 1 label

When you add the {-} to the end of the title, it will remove the Chapter label. See example below:

Remove the ‘Chapter’ label from the title

Index rmd file

The index chapter is the first chapter for a bookdown project. It contains the YAML metadata, which is a human-readable data-serialization language. YAML stands for “Yet Another Markup Language.” The YAML metadata contains information about the formatting for the bookdown project. It also contains the information for the reference rmd file (e.g., book.bib file). In this example, a description is also included.

--- 
title: "A Minimal Book Example"
author: "John Doe"
date: "`r Sys.Date()`"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib, packages.bib]
description: |
  This is a minimal example of using the bookdown package to write a book.
  set in the _output.yml file.
  The HTML output format for this example is bookdown::gitbook,
link-citations: yes
github-repo: "mbounthavong/bookdown_tutorials"
---

Other rmd Chapter files

The second and third chapters are 01-chap01 and 02-chap02.

The code for the 01-chap01.rmd file is:

# This is the R Markdown file for the first chapter {#01-chap01}
This is the `rmd` file for Chapter 1.

## First level header
The first level is generated using the `##` 

### Second level header
The second level is generated using the `###` 

#### Third level header
The third level is generated using the `####` 

The code for the 02-chap02.rmd file is:

# Second chapter example {#02-chap02}

This is the second chapter for our `bookdown` project. 

## Example reference
This is an example for citing a reference in the body of the text. 

Bounthavong and colleagues[@Bounthavong2017] reported that providers exposed to academic detailing had a greater rate of naloxone prescribing compared to providers who were unexposed to academic detailing.

The official site for all the citation styles can be found in [Citation Style Library GitHub website](https://github.com/citation-style-language/styles).

We created a hidden hyperlink by adding {#01-chap01}, which will generate the # by the chapter header. This feature is useful to make navigation easier for your e-book.

Hyperlink associated with the Chapter header

Reference / Bibliography rmd file

The fourth and last chapter is 03-references, which will contain our references. The reference file book.bib is based on the BibTex file system.

Here is the code of the @article citation that was used in the tutorial. You can call this citation using @Bounthavong2017 in the main text. (Note that in the author field, you have to use the conjunction and between each author. In BibTeX, the conjunction and is used to separate each author, not a comma. If you use a comma, the render will improperly list the authors’ names.)

@article{Bounthavong2017,
  title = {Trends in naloxone prescriptions prescribed after implementation of a National Academic Detailing Service in the Veterans Health Administration: A preliminary analysis},
  author = {Mark Bounthavong and Michael A Harvey and Daina L Wells and Sarah J Popish and Julianne Himstreet and Elizabeth M Oliva and Chad L Kay and Marcos K Lau and Priyanka P Randeria-Noor and Andrea G Phillips and Melissa L D Christopher},
  journal = {Journal of the American Pharmacists Association},
  year = {2017},
  volume = {57},
  number = {S2},
  pages = {S68-S72},
  doi = {10.1016/j.japh.2016.11.003},
}

Other citation types include (further details on field types can be found in the BibTeX wiki:

• @article
• @book
• @booklet
• @conference
• @inbook
• @incollection
• @inproceedings
• @manual
• @masterthesis
• @misc
• @phdthesis
• @proceedings
• @techreport
• @unpublished

You can set the citation style by changing this in the YAML meta data. For this exercise, we will use the AMA 11th edition citation style. The following YAML metadata has the following line: csl: https://raw.githubusercontent.com/citation-style-language/styles/master/american-medical-association.csl. The csl link is linked to the RAW code from the Citation Style Library GitHub site.

--- 
title: "A Minimal Book Example"
author: "John Doe"
date: "`r Sys.Date()`"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib, packages.bib]
csl: https://raw.githubusercontent.com/citation-style-language/styles/master/american-medical-association.csl
description: |
  This is a minimal example of using the bookdown package to write a book.
  set in the _output.yml file.
  The HTML output format for this example is bookdown::gitbook,
link-citations: yes
github-repo: "rstudio/bookdown-demo"
---

Here is an example of how you can add a citation (@Bounthavong2017) into the main text (This was provided earlier in Chapter 2’s rmd file).

Bounthavong and colleagues[@Bounthavong2017] reported that providers exposed to academic detailing had a greater rate of naloxone prescribing compared to providers who were unexposed to academic detailing.

The render should include a superscript for the citation.

Citation inserted into the main text

The 03-references.rmd file contains the following code. The {-} code denote that the “Chapter” title would be removed. Only the Header References could be shown.

`r if (knitr::is_html_output()) '
# References {-}
'`

Final References chapter render

Conclusions

The bookdown package does a pretty good job of rendering chapters along with references using specific citation styles. This tutorial provides a high-level overview on how to create chapters and add references/citations to the main text.

I plan to add more tutorials as I expand my experience with creating an e-book.

Acknowledgements

The best reference for bookdown is by Yuhui Xie’s online book, “bookdown: Authoring Books and Technical Documents with R Markdown”.

This is a great Medium article by CiteDrive for adding citations using R Markdown.

The official site for all the citation styles can be found in Citation Style Library GitHub website.

This is a work in progress, and I anticipate updating this in the future. So, stay tuned.