Introduction
This tutorial will go over the basic setup with
bookdown, an R package that is used to create HTML books.
You can create a bookdown project using R / RStudio. This
is the first part of this tutorial, and I plan on writing several more
on this subject.
Start a bookdown project
To start a bookdown project, you will need to install
the bookdown package. Once installed, you will be able to
select the bookdown project from the “File” tab.
# install.packages("bookdown")Select “New Project…” from the “File” tab, and then click on “New
Directory.” R will generate a directory for your bookdown
project, which will include several necessary files. Make sure to select
“Book project using bookdown” for the “Project Type.” Next, select a
name for your directory. In this tutorial, I used “Bookdown tutorial.”
This will be the name of the folder where you will save and edit your
bookdown project. For the “HTML” format, make sure to
select “github.” There are other formats, but for this tutorial, we’ll
use “github.”
Figure 1 - Selecting bookdown project.
Once you created your project, it should automatically open four
files: README.md, index.Rmd,
_bookdown.yml, _output.yml. Each of these
files are crucial for the bookdown project.
Figure 2 - bookdown project files.
Directory files
The files in your new bookdown project directory will
contain examples for you to modify and customize for your project.
Figure 3 - bookdown project files in the directory.
_bookdown.yml file is used for the configuration of the
book. This is where you can customize the label for each section. For
example, the current label for each section is “Chapter.” There are a
lot of options to configure your bookdown project. You can
learn more about them here.
For now, we’ll leave this at the default setting.
Figure 4 - _bookdown.yml file.
The _output.yml file contains information on the format
of the book. There are three formats: LaTeX/PDF, HTML, and ebooks. In
the default _output.yml, we see the title of the book at
the top of the table of contents, which is “A Minimal Book Example.” At
the bottom of the table of contents is the reference for the
bookdown package which is labeled as “Published with
bookdown.” You can learn more about the options for the
_output.yml here.
Figure 5 - _output.yml file.
The README.md is the README file for the project. This
is helpful when you publish this on a GitHub registry where it will be
displayed.
The index.Rmd file is the first chapter or section of
the book. Recall, in the _bookdown.yml file, the label for
the sections is “Chapter.” Hence, when you render this
bookdown project, the _index.Rmd file will be
“Chapter 1.” To prevent this, you can add {-} after the main header.
This will change “Chapter 1 About” to “About”
Figure 6 - Removing the Chapter number.
Figure 7 - Changing the section label.
Building the book
Once you have the necessary files, you can build the book. To do this, you will need to select “Build Book” in the “Environments” pane. Since this is an example, we’ll build the default tutorial book. In future tutorials, we’ll customize this for our needs.
Figure 8 - Building the book.
Conclusions
bookdown is a versatile package that allows R users to
build online books and technical documents. It has a range of options
that allow users to customize the format and output of the book. In
future tutorials, we’ll go over how to take advantage of these features
to build our own customized book.
Acknowledgements
The best reference for bookdown is by Yuhui Xie’s online
book, “bookdown:
Authoring Books and Technical Documents with R Markdown”.
This is a work in progress, and I anticipate updating this in the future. So, stay tuned.