# Render multiple R Markdown documents into a book

Render multiple R Markdown files under the current working directory
into a book. It can be used in the RStudio IDE (specifically, the `knit`
field in YAML). The `preview_chapter()` function is a wrapper of
`render_book(preview = TRUE)`.

## Usage

``` r
render_book(
  input = ".",
  output_format = NULL,
  ...,
  clean = TRUE,
  envir = parent.frame(),
  clean_envir = !interactive(),
  output_dir = NULL,
  new_session = NA,
  preview = FALSE,
  config_file = "_bookdown.yml"
)

preview_chapter(..., envir = parent.frame())
```

## Arguments

- input:

  A directory, an input filename or multiple filenames. For a directory,
  `index.Rmd` will be used if it exists in this (book) project
  directory. For filenames, if `preview = TRUE`, only files specified in
  this argument are rendered, otherwise all R Markdown files specified
  by the book are rendered.

- output_format, ..., clean, envir:

  Arguments to be passed to
  `rmarkdown::`[`render()`](https://pkgs.rstudio.com/rmarkdown/reference/render.html).
  For `preview_chapter()`, `...` is passed to `render_book()`. See
  `rmarkdown::`[`render()`](https://pkgs.rstudio.com/rmarkdown/reference/render.html)
  and [the bookdown reference
  book](https://pkg.yihui.org/bookdown/build-the-book.html) for details
  on how output formatting options are set from YAML or parameters
  supplied by the user when calling `render_book()`.

- clean_envir:

  This argument has been deprecated and will be removed in future
  versions of bookdown.

- output_dir:

  The output directory. If `NULL`, a field named `output_dir` in the
  configuration file `_bookdown.yml` will be used (possibly not
  specified, either, in which case a directory name `_book` will be
  used).

- new_session:

  Whether to use new R sessions to compile individual Rmd files (if not
  provided, the value of the `new_session` option in `_bookdown.yml` is
  used; if this is also not provided, `new_session = FALSE`).

- preview:

  Whether to render and preview the input files specified by the `input`
  argument. Previewing a certain chapter may save compilation time as
  you actively work on this chapter, but the output may not be accurate
  (e.g. cross-references to other chapters will not work).

- config_file:

  The book configuration file.

## Details

There are two ways to render a book from Rmd files. The default way
(`new_session = FALSE`) is to merge Rmd files into a single file and
render this file. You can also choose to render each individual Rmd file
in a new R session (`new_session = TRUE`).

## Examples

``` r
# see https://pkg.yihui.org/bookdown for the full documentation
if (file.exists("index.Rmd")) bookdown::render_book("index.Rmd")
if (FALSE) { # \dontrun{
# will use the default format defined in index.Rmd or _output.yml
bookdown::render_book("index.Rmd")
# will use the options for format defined in YAML metadata
bookdown::render_book("index.Rmd", "bookdown::pdf_book")
# If you pass an output format object, it must have all the options set
bookdown::render_book("index.Rmd", bookdown::pdf_book(toc = FALSE))

# will render the book in the current directory
bookdown::render_book()
# this is equivalent to
bookdown::render_book("index.Rmd")
# will render the book living in the specified directory
bookdown::render_book("my_book_project")
} # }
```