1.3 Usage

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):

  • index.Rmd

    # Preface {-}

In this book, we will introduce an interesting
method.

  • 01-intro.Rmd

    # Introduction

This chapter is an overview of the methods that
we propose to solve an **important problem**.

  • 02-literature.Rmd

    # Literature

Here is a review of existing methods.

  • 03-method.Rmd

    # Methods

We describe our methods in this chapter.

  • 04-application.Rmd

    # Applications

Some _significant_ applications are demonstrated
in this chapter.

## Example one

## Example two

  • 05-summary.Rmd

    # Final Words

We have finished a nice book.

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/.

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,

rmd_files: ["index.Rmd", "abstract.Rmd", "intro.Rmd"]

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.,

rmd_files:
  html: ["index.Rmd", "abstract.Rmd", "intro.Rmd"]
  latex: ["abstract.Rmd", "intro.Rmd"]

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::pdf_book, bookdown::gitbook, bookdown::html_book, and 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:

bookdown::render_book("foo.Rmd", "bookdown::gitbook")
bookdown::render_book("foo.Rmd", "bookdown::pdf_book")
bookdown::render_book("foo.Rmd", bookdown::gitbook(lib_dir = "libs"))
bookdown::render_book("foo.Rmd", bookdown::pdf_book(keep_tex = TRUE))

To use 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.,

---
site: "bookdown::bookdown_site"
output:
  bookdown::gitbook:
    lib_dir: "book_assets"
  bookdown::pdf_book:
    keep_tex: yes
---

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:

--- 
title: "Authoring A Book with R Markdown"
author: "Yihui Xie"
date: "`r Sys.Date()`"
site: "bookdown::bookdown_site"
output:
  bookdown::gitbook: default
documentclass: book
bibliography: ["book.bib", "packages.bib"]
biblio-style: apalike
link-citations: yes
---

  1. This function calls bookdown::render_book().↩︎