Thread by @rfortherest

The {bookdown} package is a great way to publish an #rstats book online. It's what I'm using to make R Without Statistics.

Here's a thread with step-by-step video instructions to help you get started with {bookdown}.

Prefer a blog post? Check out rfor.us/bookdown.

First, you'll want to install bookdown, same as any other package.

Next you'll want to create a new RStudio project to hold all of the materials for your bookdown project. When you do so, choose "book project using bookdown." You'll be able to select between the gitbook and bs4 themes (R Without Statistics uses the latter).

When you create a new book project using bookdown, you’ll get some default content. Understanding what the various .Rmd, .yml, and other files are is key. Let’s take a look at the default content and understand how we can render this to create our book.

bookdown also creates a PDF and, most importantly for us, a website for our book. Let's look at those.

Now that we’ve seen the default content, let’s modify it. First, let’s look at the index.Rmd file. Here we can do things like change the title and author of our book and more.

Creating a new bookdown project gives us default content. Let’s now learn how to remove that.

We can also of course add our own content. Let's do that next.

In your RStudio project, you have two YAML files that control the output for the entire bookdown project. These files are _bookdown.yml and _output.yml. Let's look first _bookdown.yml.

The _bookdown.yml can help us to adjust the order of files when we create our book. By default, bookdown will order chapters in alphabetical order of our Rmd files.

But if we add content to the _bookdown.yml we can manually specify the order of our chapters.

The second bookdown-specifc YAML file is _output.yml. In this file, we can change the look and feel of our book. In this video, I show how to change the primary color your book uses as well as make changes using custom CSS.

By default, bookdown adds numbers to chapters. You can see this in R for Data Science.

Sometimes, you may want to remove this numbering (I do so in R Without Statistics). To do so, you’ll need to add the marker {-} to all headings if you’re using the bs4 output format (if you’re using gitbook, you can do this in the _output.yml file).

When you have a long bookdown book, you’ll probably want to break it up into sections. I do this in R Without Statistics to break up the chapters into several sections.

To do this in bookdown, you’ll need to add content to the RMarkdown file that shows up immediately after the section break. Technically, bookdown refers to these “sections” as parts, but no matter what they’re called, here’s how to create them.

Once you’ve learned how to create and customize a book using the bookdown package, you’re probably wondering how to share it. There are many ways to do this, but the most effective (at least for projects that are public) is to post it online.

To do this, you’ll need to first post your code on GitHub. If you’re new to this, check out this post on using Git and GitHub with R.

rfortherestofus.com/2021/02/how-to…

Here's how to post your bookdown project as a GitHub repository.

Now you’ve posted your code on GitHub. The problem, though, is that GitHub only shows the code, not the rendered versions of your code.

You probably don’t want your users to read the raw HTML that makes up a bookdown book. To enable them to see your book, we’ll need to host our HTML files somewhere. My favorite service for doing this is @netlify.

Netlify has a generous free tier that allows you to post your book project online. Here’s how to do that.

You can even watch as your book is (very quickly!) deployed.

I hope that helps you to get started with bookdown! Don't forget that you can find this same content as a blog post (rfor.us/bookdown). Thanks for sharing!