R Bookdown Example

Posted on  by admin
  1. Bookdown Demo
  2. R Markdown Bookdown
R bookdown examples

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

  • 01-intro.Rmd

  • 02-literature.Rmd

  • 03-method.Rmd

  • 04-application.Rmd

  • 05-summary.Rmd

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

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

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:

  1. Download the GitHub repository https://github.com/rstudio/bookdown-demo as a Zip file, then unzip it locally.

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

  3. Install the R package bookdown:

  4. Open the bookdown-demo repository you downloaded in RStudio by clicking bookdown-demo.Rproj.

  5. Open the R Markdown file index.Rmd and click the button Build Book on the Build tab of RStudio.

If you are planning on printing your book to PDF, you will need a LaTeX distribution. We recommend that you install TinyTeX (which includes XeLaTeX): https://yihui.org/tinytex/.

Bookdown Demo

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.