knitr logo

knitr: elegant, flexible, and fast dynamic report generation with R

Options

Chunk options and package options

2020-06-30


The knitr package provides a lot of chunk options for customizing nearly all components of code chunks, such as the source code, text output, plots, and the language of the chunk. It also offers some options at the package level to customize the knitting process. This page documents all chunk options and package options available in knitr. The default values of these options are in parentheses in the list items.

Chunk Options

Chunk options are written in chunk headers. The syntax for chunk headers depends on the document format, e.g., for .Rnw documents (R + LaTeX), chunk headers are written with << >>=, and for .Rmd documents, chunk headers are written with ```{r}. The examples below are primarily for .Rmd documents (R Markdown), but in most cases, the chunk options can be used with any document format.

Chunk options are written in the form tag=value like this:

```{r, my-chunk, echo=FALSE, fig.height=4, dev='jpeg'}
```

A special chunk option is the chunk label (e.g., my-chunk in the above example). Only the chunk label does not need a tag (i.e., you only provide the value). If you prefer the form tag=value, you could also use the chunk option label explicitly, e.g.,

```{r, label='my-chunk'}
```

The chunk label for each chunk is assumed to be unique within the document. This is especially important for cache and plot filenames, because these filenames are based on chunk labels. Chunks without labels will be assigned labels like unnamed-chunk-i, where i is an incremental number.

You may use knitr::opts_chunk$set() to change the default values of chunk options in a document. For example, you may put this in the first code chunk of your document:

```{r, setup, include=FALSE}
knitr::opts_chunk$set(
  comment = '', fig.width = 6, fig.height = 6
)
```

Below are a few more tips about chunk options:

  1. The chunk header must be written on one line. You must not break the line.

  2. Try to avoid spaces, periods (.), and underscores (_) in chunk labels and paths. If you need separators, you are recommended to use hyphens (-) instead. For example, setup-options is a good label, whereas setup.options and chunk 1 are bad; fig.path = 'figures/mcmc-' is a good path for figure output, and fig.path = 'markov chain/monte carlo' is bad.

  3. All option values must be valid R expressions. You may think of them as values to be passed to function arguments.

    • For example, options that take character values must be quoted, e.g., results = 'asis' and out.width = '\\textwidth' (remember that a literal backslash needs double backslashes).
    • In theory, the chunk label should be quoted, too. However, for the sake of convenience, it will be automatically quoted if you did not (e.g., ```{r, 2a} will parsed as ```{r, '2a'}).
    • You can write arbitrarily complicated expressions as long as they are valid R code.

Below is a list of chunk options in knitr documented in the format “option: (default value; type of value)“.

Code evaluation

Text output

Code decoration

Cache

Plots

There are two hidden options that are not designed to be set by users: fig.cur (the current figure number or index when there are multiple figures), and fig.num (the total number of figures in a chunk). The purpose of these two options is to help knitr deal with the filenames of multiple figures as well as animations. In some cases, we can make use of them to write animations into the output using plot files that are saved manually (see the graphics manual for examples).

Animation

Code chunk

Child documents

Language engines

Option templates

Extracting source code

Other chunk options

Package Options

The package options can be changed using the object knitr::opts_knit (not to be confused with knitr::opts_chunk). For example:

knitr::opts_knit$set(progress = TRUE, verbose = TRUE)

See ?knitr::opts_knit for the alternative approach to setting package options using the R base function options().

Available package options are as follows: