A typical bookdown book contains multiple chapters, and one chapter lives in one R Markdown file, with the filename extension
.Rmd. Each R Markdown file must start immediately with the chapter title using the first-level heading, e.g.,
# Chapter Title. All R Markdown files must be encoded in UTF-8, especially when they contain multi-byte characters such as Chinese, Japanese, and Korean. Here is an example (the bullets are the filenames, followed by the file content):
By default, bookdown merges all Rmd files by the order of filenames, e.g.,
01-intro.Rmd will appear before
02-literature.Rmd. Filenames that start with an underscore
_ are skipped. If there exists an Rmd file named
index.Rmd, it will always be treated as the first file when merging all Rmd files. The reason for this special treatment is that the HTML file
index.html to be generated from
index.Rmd is usually the default index file when you view a website, e.g., you are actually browsing http://yihui.org/index.html when you open http://yihui.org/.
- This will create a new directory with an example book as template. You can build the HTML version of this example book without doing any modification: Go into the Build Pane in the RStudio IDE; Click on Build Book bookdown::gitbook; You can also run bookdown::renderbook in the R console. Learn more about using bookdown in the Getting started section.
- When using bookdown (single document), if I set both sectionnumbering = 'yes' and figcaption = 'yes', the figures are numbered X.2 (where X is the section number). If sectionnumber = 'no', the figures are numbered sequentially (Fig 1, 2.), but sections numbers are lost. Is there a way to get figures numbered sequentially without losing the section numbers?
You can override the above behavior by including a configuration file named
_bookdown.yml in the book directory. It is a YAML file (https://en.wikipedia.org/wiki/YAML), and R Markdown users should be familiar with this format since it is also used to write the metadata in the beginning of R Markdown documents (you can learn more about YAML in Section B.2). You can use a field named
rmd_files to define your own list and order of Rmd files for the book. For example,
Bookdown: Authoring Books and Technical Documents with R Markdown. This book explains how to use bookdown to write books and technical documents. The bookdown package is built on top.
In this case, bookdown will use the list of files you defined in this YAML field (
index.Rmd will be added to the list if it exists, and filenames starting with underscores are always ignored). If you want both HTML and LaTeX/PDF output from the book, and use different Rmd files for HTML and LaTeX output, you may specify these files for the two output formats separately, e.g.,
Although we have been talking about R Markdown files, the chapter files do not actually have to be R Markdown. They can be plain Markdown files (
.md), and do not have to contain R code chunks at all. You can certainly use bookdown to compose novels or poems!
At the moment, the major output formats that you may use include
bookdown::epub_book. There is a
bookdown::render_book() function similar to
rmarkdown::render(), but it was designed to render multiple Rmd documents into a book using the output format functions. You may either call this function from command line directly, or click the relevant buttons in the RStudio IDE. Here are some command-line examples:
render_book and the output format functions in the RStudio IDE, you can define a YAML field named
site that takes the value
bookdown::bookdown_site,1 and the output format functions can be used in the
output field, e.g.,
Then you can click the
Build Book button in the
Build pane in RStudio to compile the Rmd files into a book, or click the
Knit button on the toolbar to preview the current chapter.
More bookdown configuration options in
_bookdown.yml are explained in Section 4.4. Besides these configurations, you can also specify some Pandoc-related configurations in the YAML metadata of the first Rmd file of the book, such as the title, author, and date of the book, etc. For example:
1.2 Get started
The easiest way for beginners to get started with writing a book with R Markdown and bookdown is through the demo
bookdown-demo on GitHub:
Download the GitHub repository https://github.com/rstudio/bookdown-demo as a Zip file, then unzip it locally.
Install the RStudio IDE. Note that you need a version higher than 1.0.0. Please download the latest version if your RStudio version is lower than 1.0.0.
Install the R package bookdown:
bookdown-demorepository you downloaded in RStudio by clicking
Open the R Markdown file
index.Rmdand click the button
Build Bookon the
Buildtab of RStudio.
Now you should see the index page of this book demo in the RStudio Viewer. You may add or change the R Markdown files, and hit the
Knit button again to preview the book. If you prefer not to use RStudio, you may also compile the book through the command line. See the next section for details.
R Markdown Bookdown
Although you see quite a few files in the
bookdown-demo example, most of them are not essential to a book. If you feel overwhelmed by the number of files, you can use this minimal example instead, which is essentially one file
index.Rmd: https://github.com/yihui/bookdown-minimal. The
bookdown-demo example contains some advanced settings that you may want to learn later, such as how to customize the LaTeX preamble, tweak the CSS, and build the book on GitHub, etc.