I’m currently working on three different books: Mastering Software Development in R,Developing Data Products, andThe Unix Workbench. My increasedlevel of productivity has been made possible in part by bookdown,an R package by the incredible and prolificYihui Xie which transforms R Markdown documents into a book that looks beautiful online with EPUB and PDF versions included.
The LaTeX/PDF output format is provided by pdfbook in bookdown. There is not a significant difference between pdfbook and the pdfdocument format in rmarkdown. Slides Download pdf. Venue: Woodburn 200, IU, Bloomington. Dissertating with RMarkdown and Bookdown. DoPDF is a free PDF converter that can be used to create PDF from any printable document. It's truly free for both personal and commercial use. This is a minimal example of using the bookdown package to write a book. The output format for this example is bookdown::gitbook.
Getting started with bookdown is not yet a totally straightforward process so Ithought 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 absolutesmallest amount of boilerplatecode required to start a bookdown book which you can findhere. To get started you shouldeither fork and clone the repository or download it as a zip. There are threeconfiguration files you need to worry about in the repo, so let’s take a lookat each of them starting with
The only line you should change here is the title of the book, which in thiscase is
A Minimal Bookdown Book. Moving on to
book_filename field determines what the name of the PDF and EPUB versionsof your book will be called. In the case of this book the PDF version would be
chapter_name field is a string that is appended tothe front of each chapter heading, followed by the chapter number. Chapterheadings are designated by H1 tags in R Markdown which are usually createdwith a single pound sign (
#). So for example in the file
01-Introduction.Rmdthe first H1 tag is
# Introduction which becomes “Chapter 1 Introduction”when the book is rendered. The
repo field just designates a GitHub repositoryassociated with this book but this is not a required field.
output_dirfield determines the directory where the HTML files for your book will berendered. If you don’t set this field your book will be rendered in adirectory called
_book/, however if you’re going to be sharing your book withGitHub Pages I highly recommend specifying the
docs directory for
output_dir. GitHub Pages has anew featurewhich allows you to use a
docs/ folder in the master branch of your repo topublish a static website. This allows you to track the source files for yourbook and the published HTML files in the same branch, eliminating the need forthat pesky
rmd_files field is optional. If it is not specified then all Rmd files atthe 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
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 authorsusually put the Preface and/or the Introduction in this file. At the top of thisfile is a slice of yaml frontmatter that looks like this:
You should change the
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 bookcouldn’t be easier if you’re familiar with R Markdown. Just write Rmd filesin the root directory of your book (where
index.Rmd is) and run
bookdown::render_book('index.Rmd') periodically to compile your book. You canpreview the book by opening up the
index.html file in the directory where yourbook is rendered (
docs/index.html in the case of
bookdown-start). It’s alsogood practice to name your Rmd files so that they’re ordered, which you can seeI’ve done with the prefixes of
02-, etc. You can then publish the bookon GitHub Pages or you can upload the book to bookdown.orgwith the
You can use Travis CI to set up continuousintegration for your book. If you’re unfamilar with continuous integration youshould read this shortchapter onthe subject. To use Travis for your book you need to include three files to theroot of your book’s GitHub repo. You can copy the first two of these fileswithout modifying them:
Create a file called
.Rbuildignore and copy, paste, and save the following:
Name this file
Here’s a starter
DESCRIPTION file but you may need to modify it:
Specifically you should add R packages to the
Remotes fields ifthe R code in your book relies in certain packages. For more information about
DESCRIPTION files see thisshort book section.
Make sure to enable continuous integration for your book’s GitHub repo onTravis, 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 Ifound on bookdown.org combined with a few hours of playing with and tweaking bookdown. Mybookdown-startrepo is just a pared down version of Yihui’sbookdown-demo repo. I use theworkflow described above whenever I start a book and if you have anyimprovements, suggestions, or cool hacks I’m interested in hearing about them.For a complete and robust treatment of using bookdown you should readYihui’s book: Authoring Books and Technical Documents with R Markdown. Thanks again to Yihui forcreating this awesome package and for providing feedback for this post.
5.1 Build the book
To build all Rmd files into a book, you can call the
render_book() function in bookdown. Below are the arguments of
The most important argument is
output_format, which can take a character string of the output format (e.g.,
'bookdown::gitbook'). You can leave this argument empty, and the default output format will be the first output format specified in the YAML metadata of the first Rmd file or a separate YAML file
_output.yml, as mentioned in Section 4.4. If you plan to generate multiple output formats for a book, you are recommended to specify all formats in
Bookdown To Pdf
Once all formats are specified in
_output.yml, it is easy to write an R or Shell script or Makefile to compile the book. Below is a simple example of using a Shell script to compile a book to HTML (with the GitBook style) and PDF:
The Shell script does not work on Windows (not strictly true, though), but hopefully you get the idea.
... is passed to the output format function. Arguments
envir are passed to
rmarkdown::render(), to decide whether to clean up the intermediate files, and specify the environment to evaluate R code, respectively.
The output directory of the book can be specified via the
output_dir argument. By default, the book is generated to the
_book directory. This can also be changed via the
output_dir field in the configuration file
_bookdown.yml, so that you do not have to specify it multiple times for rendering a book to multiple output formats. The
new_session argument has been explained in Section 1.4. When you set
preview = TRUE, only the Rmd files specified in the
input argument are rendered, which can be convenient when previewing a certain chapter, since you do not recompile the whole book, but when publishing a book, this argument should certainly be set to
Bookdown Pdf Download
A number of output files will be generated by
render_book(). Sometimes you may want to clean up the book directory and start all over again, e.g., remove the figure and cache files that were generated automatically from knitr. The function
clean_book() was designed for this purpose. By default, it tells you which output files you can possibly delete. If you have looked at this list of files, and are sure no files were mistakenly identified as output files (you certainly do not want to delete an input file that you created by hand), you can delete all of them using
bookdown::clean_book(TRUE). Since deleting files is a relatively dangerous operation, we would recommend that you maintain your book through version control tools such as GIT, or a service that supports backup and restoration, so you will not lose certain files forever if you delete them by mistake.