1 How to use this template

The goal of this template is to make it easy to get started on writing a bookdown book. The word ‘book’ might be a misnomer because you can also use it to write notes, a manual (similar to this bookdown), a thesis, and many other things.

If you have enough time, the best way to get started is to read the bookdown book. For those in a hurry, we list the important steps below.

1.1 Setup

  1. Clone this template from GitHub. The easiest way to do this is to open RStudio and select File -> New Project -> Version Control -> Git. The repository URL of this template is “https://github.com/rethinkpriorities/bookdown-template”. After entering this, and changing some of the other settings if you want to, click on Create Project.

  2. Install (or update) the rethinkpriorities R package. This package includes the unique format that we developed.

    1. You can install the package with the following code: devtools::install_github("rethinkpriorities/rp-r-package")
  3. To preview the template, go to the Build tab (next to Environment, History, and Connection) and click on “Build Website”. This will open the book in the Viewer pane.

1.2 Usage

The template is in and of itself not interesting, so you need to adapt the content. The first thing to adapt are the contents of index.Rmd. You should change some of the information at the top of the file (between the two --- symbols). These are the YAML options and you can change them to alter the meta-information of the book or to change some of the settings.

After changing the content of index.Rmd, you should start adding chapters. In order for the book to include the chapter when you build it, you should change the contents of _bookdown.yml. Make sure to adapt the file paths in the rmd_files option so it refers to the new chapter. The order of these file paths also determines the order of the chapters in the book. For example, the default value of rmd_files is:

rmd_files: [
  "index.Rmd", 
  "how-to.Rmd", 
  "toc.Rmd",
  "code.Rmd", 
  "citations.Rmd", 
  "blockquotes.Rmd", 
  "footnotes.Rmd", 
  "foldable-sections.Rmd", 
  "alerts.Rmd", 
  "tables.Rmd", 
  "EA-forum.Rmd"
]

1.3 Customization

There are several customization options that you can use to tweak the way the book looks or behaves.

  • use_littlefoot: Set this option to true if you want footnotes to show up as popovers in the text. Set this option to false if you want to opt out of this and use normal footnotes that show up at the bottom of the page.

  • sidebar_width: Set this option to vary the width of the sidebar that contains the table of contents. It should be any css-valid value such as 250px or 16rem.

If there are other features you want, feel free to create an issue in the bookdown-template repository to request it.

1.4 Known issues

Pandoc

If building the book ends up looking different on your device, check whether you are using the same version of Pandoc. This bookdown format relies on the version of Pandoc that comes with RStudio. You can check the version and location of your Pandoc installation by running rmarkdown::find_pandoc().

If it turns out that your version of Pandoc is different, you can uninstall it and restart RStudio to use the version that comes with RStudio.