Introduction

This is a cookbook for educators who would like to use bookdown to organize and deliver educational content for their audience. Despite the name, using bookdown doesn’t mean that what you make has to be a book–but a bookdown site does come with some built-in features (e.g. its hallmark heavy-duty table of contents) that make it well-suited for long-form content (or many R Markdown files that can be organized in a chronological way). This, and the lack of a navbar make a bookdown site feel somewhat less like a typical website and a bit more like a textbook, but how you use it is up to you. You can place an entire course-worth’s of materials in a bookdown book, or you could pare down your TOC headers and create a site for a short workshop. This rstudio4edu resource is itself a bookdown!

In short, bookdown’s main features include:

A very prominent table of contents
Cross-references
Numbered figures, equations, and tables
Distribution of your book as a PDF, an HTML website, etc.
A built-in search feature (that’s a bit unintuitive to use)

Make a book

Here, we’ll guide you through creating an out-of-the-box bookdown book. We make only the most minimal changes to content and style necessary to get you a shareable bookdown site.

Make it yours

You’ll personalize your book’s content here by adding chapters.

Caring for your book

You’ll develop a workflow for editing your book, adding new content, and hiding pages that are works-in-progress.

Dress it up

Here, you’ll find instructions for no-fuss website customizations that leverage built-in features that do not rely on knowing, learning, or using CSS.

Make it fancier

If you want to take your customization further, we show you how to make your book look like the crème de la crème with some CSS, HTML, and (a teensy bit of) JavaScript.

What are we making?

If you have experience making basic R Markdown sites, then you can think of a bookdown as an R Markdown site with additional YAML files (there are three, which take care of configuration and stitching the site together) and some more rigid rules about what can start each document.

[INSERT ANALOGY HERE FOR THE FILE TYPES]

As we build our first book, we’ll want to keep in mind these elements:

Level 1 headers, become new site pages/ book chapters
Three YAMLS, one of which is index.Rmdand works as it does for RMD sites
.Rmd file order, can be set manually in one of the YAMLs

Additionally, just like we did for R Markdown sites, we’ll demo how to publish your bookdown site for free using GitHub Pages, so we’ll also need:

A docs/ folder which will be the folder that we will use as the “boarding area” for your rendered site files to deploy on GitHub Pages.
To turn on GitHub Pages for your repository.

There are certainly other options for publishing (aka deploying) a bookdown website. For an overview of other options, you may reference: https://rstudio.github.io/distill/publish_website.html.

Pros and cons of using bookdown sites

Pros: Feels like working with a regular RMD site, once you get the hang of the YAMLS and the Level 1 headers.
Cons: Three YAMLs. Can’t use tabsets. Your directory will be likely be filled with many .Rmds, and there’s no good way to organize them into subdirectories.

Is this cookbook for you?

Pre-requisites:

You have a GitHub account
You are comfortable with the basics of using R and RStudio
You understand how R projects work
You understand the difference between a regular R script and an R Markdown document
You have some familiarity working with R Markdown documents
It is helpful, but not necessary if you have some familiarity with making regular RMD sites

What you’ll learn:

How to compile multiple R Markdown files into a Bookdown site
How to publish your Bookdown for free via GitHub Pages
How to add basic customization using built in options
How to take the customization even further by using HTML, CSS, and a little bit of JavaScript

Learning resources

Bookdown examples from competition