Skip to main content

I’m currently working on three different books: Mastering Software Development in R, Developing Data Products, and The Unix Workbench. My increased level of productivity has been made possible in part by bookdown, an R package by the incredible and prolific Yihui Xie which transforms R Markdown documents into a book that looks beautiful online with EPUB and PDF versions included.

Getting started with bookdown is not yet a totally straightforward process so I thought I would share what I do when I start a bookdown book. First open up your favorite R console and install bookdown if you haven’t already:


I created a GitHub repository which contains what I consider to be the absolute smallest amount of boilerplate code required to start a bookdown book which you can find here. To get started you should either fork and clone the repository or download it as a zip. There are three configuration files you need to worry about in the repo, so let’s take a look at each of them starting with _output.yml:

  css: style.css
  split_by: chapter
      collapse: subsection
      before: |
        <li><a href="./">A Minimal Bookdown Book</a></li>
      after: |
        <li><a href="" target="blank">Published with bookdown</a></li>
    in_header: preamble.tex
  latex_engine: xelatex
  citation_package: natbib
  stylesheet: style.css

The only line you should change here is the title of the book, which in this case is A Minimal Bookdown Book. Moving on to _bookdown.yml:

book_filename: "bookdown-start"
chapter_name: "Chapter "
output_dir: docs
rmd_files: ["index.Rmd", "01-Introduction.Rmd", "02-Diving-In.Rmd"]
clean: [packages.bib, bookdown.bbl]
new_session: yes

The book_filename field determines what the name of the PDF and EPUB versions of your book will be called. In the case of this book the PDF version would be bookdown-start.pdf. The chapter_name field is a string that is appended to the front of each chapter heading, followed by the chapter number. Chapter headings are designated by H1 tags in R Markdown which are usually created with a single pound sign (#). So for example in the file 01-Introduction.Rmd the first H1 tag is # Introduction which becomes “Chapter 1 Introduction” when the book is rendered. The repo field just designates a GitHub repository associated with this book but this is not a required field.

The output_dir field determines the directory where the HTML files for your book will be rendered. If you don’t set this field your book will be rendered in a directory called _book/, however if you’re going to be sharing your book with GitHub Pages I highly recommend specifying the docs directory for output_dir. GitHub Pages has a new feature which allows you to use a docs/ folder in the master branch of your repo to publish a static website. This allows you to track the source files for your book and the published HTML files in the same branch, eliminating the need for that pesky gh-pages branch.

The rmd_files field is optional. If it is not specified then all Rmd files at the root of your book directory are rendered as chapters in your book. Alternatively you can list the files you want to be rendered like I have in _bookdown.yml. The new_session field is also optional. If you specify new_session: yes then each Rmd file is rendered in its own R session, otherwise all Rmd files in your book are rednered in the same R session.

The next bit of configuration you should consider is in the index.Rmd file. This file serves as the cover and first few pages of your book, so authors usually put the Preface and/or the Introduction in this file. At the top of this file is a slice of yaml frontmatter that looks like this:

title: "A Minimal Bookdown Book"
author: "Sean Kross"
date: "2016-12-02"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib]
biblio-style: apalike
link-citations: yes
github-repo: seankross/bookdown-start
url: 'http\://'
description: "Everything you need (and nothing more) to start a bookdown book."

You should change the title, author, date, github-repo, url, and description fields to customize your book. I omitted a field called cover-image where you can specify the path to a image file for the cover of your book (I know .png works for sure).

Once you have those three configuration flies set up writing a bookdown book couldn’t be easier if you’re familiar with R Markdown. Just write Rmd files in the root directory of your book (where index.Rmd is) and run bookdown::render_book("index.Rmd") periodically to compile your book. You can preview the book by opening up the index.html file in the directory where your book is rendered (docs/index.html in the case of bookdown-start). It’s also good practice to name your Rmd files so that they’re ordered, which you can see I’ve done with the prefixes of 01-, 02-, etc. You can then publish the book on GitHub Pages or you can upload the book to with the publish_book() function.

Adding Travis

You can use Travis CI to set up continuous integration for your book. If you’re unfamilar with continuous integration you should read this short chapter on the subject. To use Travis for your book you need to include three files to the root of your book’s GitHub repo. You can copy the first two of these files without modifying them:

Create a file called .Rbuildignore and copy, paste, and save the following:


Name this file .travis.yml:

language: r
cache: packages

  - Rscript -e 'bookdown::render_book("index.rmd")'

Here’s a starter DESCRIPTION file but you may need to modify it:

Package: placeholder
Title: Does not matter.
Version: 0.0.1
Imports: bookdown
Remotes: rstudio/bookdown

Specifically you should add R packages to the Imports or Remotes fields if the R code in your book relies in certain packages. For more information about DESCRIPTION files see this short book section.

Make sure to enable continuous integration for your book’s GitHub repo on Travis, then add, commit, and push these files. Check the build after a few minutes to confirm that you have CI set up for your book.


Most of this post has been cobbled together from public GitHub repositories I found on combined with a few hours of playing with and tweaking bookdown. My bookdown-start repo is just a pared down version of Yihui’s bookdown-demo repo. I use the workflow described above whenever I start a book and if you have any improvements, suggestions, or cool hacks I’m interested in hearing about them. For a complete and robust treatment of using bookdown you should read Yihui’s book: Authoring Books and Technical Documents with R Markdown. Thanks again to Yihui for creating this awesome package and for providing feedback for this post.