An .Rmd file is text: a YAML header, Pandoc
Markdown and code chunks. The header is read by the
rmarkdown package and the chunks by knitr.
Sources: knitr’s chunk options page
(every option, default, label rules and the #| form) and the book
R Markdown: The Definitive Guide,
chapters on R code, output formats, language engines and parameterised reports.
YAML header
| Key | Meaning |
|---|---|
output | The output format. Built into rmarkdown, written without a prefix: beamer_presentation, context_document, github_document, html_document, ioslides_presentation, latex_document, md_document, odt_document, pdf_document, powerpoint_presentation, rtf_document, slidy_presentation, word_document. Formats from other packages carry the package name, e.g. tufte::tufte_html. |
params | Parameters of a parameterised report, one per line; !r before a value makes it an R expression. |
Other header keys, such as title, are document metadata passed on to
Pandoc.
Chunks and inline code
| Form | Meaning |
|---|---|
```{r} … ``` | An R code chunk. |
```{r label, echo=FALSE, fig.width=5} | Options inside the braces, separated by commas. The label is optional, takes no value and comes first; it should be unique, and letters, digits and dashes are recommended. Unlabelled chunks get unnamed-chunk-1, -2 and so on. |
#| echo: false lines inside the chunk | Options in YAML syntax, one per line; values must be YAML, not R expressions; they override options in the header. |
```{python} and so on | Chunks in other languages. knitr lists 65 engines: awk, bash, coffee, gawk, groovy, haskell, lein, mysql, node, octave, perl, php, psql, Rscript, ruby, sas, scala, sed, sh, stata, zsh, asis, asy, block, block2, bslib, c, cat, cc, comment, css, ditaa, dot, embed, eviews, exec, fortran, fortran95, go, highlight, js, julia, python, R, Rcpp, sass, scss, sql, stan, targets, tikz, verbatim, theorem, lemma, corollary, proposition, conjecture, definition, example, exercise, hypothesis, proof, remark, solution, marginfigure. |
`r pi * x^2` | Inline R code: the value is inserted into the text. |
child option | Path to a child document to include. |
Chunk options
Every option knitr documents, with its default. Options can be set per chunk or for
all chunks with knitr::opts_chunk$set().
| Group | Option | Default | Meaning |
|---|---|---|---|
| Evaluation | eval | TRUE | Run the code; or numbers of the expressions to run. |
| Text output | echo | TRUE | Show the code; or numbers of expressions. |
results | 'markup' | 'markup', 'asis' (raw), 'hold' (after the code), 'hide'. | |
collapse | FALSE | Merge code and output into one block. | |
warning, message, error | TRUE | Keep warnings, messages, errors (error=FALSE stops on an error). | |
include | TRUE | FALSE runs the chunk but shows nothing. | |
tab.cap | NULL | Table caption. | |
strip.white | TRUE | Remove blank lines at the start and end of the code. | |
class.output, class.message, class.warning, class.error | NULL | Classes for those output blocks. | |
attr.output, attr.message, attr.warning, attr.error | NULL | Attributes for those output blocks. | |
render | knitr::knit_print | Function that prints visible values. | |
split | FALSE | Write output to separate files. | |
| Code decoration | tidy, tidy.opts | FALSE, NULL | Reformat the code, and the formatter’s options. |
prompt | FALSE | Add > prompts. | |
comment | '##' | Prefix of output lines. | |
highlight | TRUE | Syntax highlighting. | |
class.source, attr.source, lang | NULL | Class, attributes and language name of the code block. | |
size, background | 'normalsize', '#F7F7F7' | LaTeX font size and background colour of chunk output in Rnw documents. | |
indent | set by the parser | Indentation of the chunk in the source. | |
| Cache | cache | FALSE | Cache the results. |
cache.path | 'cache/' | Where. | |
cache.vars, cache.globals, cache.comments | NULL | Variables saved, globals tracked, whether comments change the cache key. | |
cache.lazy | TRUE | Load cached objects lazily. | |
cache.rebuild | FALSE | Force a re-run. | |
dependson, autodep | NULL, FALSE | Chunks this cache depends on; work them out automatically. | |
| Plots | fig.path | 'figure/' | Prefix of figure file names. |
fig.keep | 'high' | 'high', 'none', 'all', 'first', 'last', or numbers. | |
fig.show | 'asis' | 'asis', 'hold', 'animate', 'hide'. | |
dev, dev.args, fig.ext | 'pdf' for LaTeX, 'png' for HTML and Markdown | Graphics device, its arguments, file extension. | |
dpi | 72 | Resolution. | |
fig.width, fig.height | 7 | Size in inches. | |
fig.asp, fig.dim | NULL | Aspect ratio; width and height together. | |
out.width, out.height, out.extra | NULL | Display size and extra attributes. | |
fig.retina | 1 | Pixel ratio for HTML. | |
resize.width, resize.height | NULL | LaTeX resize dimensions for TikZ graphics. | |
fig.align | 'default' | 'default', 'left', 'right', 'center'. | |
fig.link, fig.cap, fig.alt, fig.note, fig.scap | NULL | Link, caption, alternative text, note, short caption. | |
fig.env, fig.pos, fig.topcaption | 'figure', '', FALSE | LaTeX environment, position, caption above. | |
fig.lp, fig.id | 'fig:', NULL | Label prefix; figure IDs. | |
fig.subcap, fig.ncol, fig.sep | NULL | Sub-figure captions and layout. | |
fig.process, fig.showtext | NULL | Post-process figure files; use showtext fonts. | |
external, sanitize | TRUE, FALSE | TikZ options. | |
webshot, screenshot.force, screenshot.opts, screenshot.alt | NULL | Screenshots of HTML widgets for non-HTML output. | |
fig.cur, fig.num | set by knitr | Current figure number and count (read only). | |
| Animation | interval | 1 | Seconds per frame. |
animation.hook | knitr::hook_ffmpeg_html | How frames become an animation. | |
aniopts | 'controls,loop' | LaTeX animate options. | |
ffmpeg.bitrate, ffmpeg.format | '1M', 'webm' | Video settings. | |
| Code source | code, file | NULL | Code to use instead of the chunk’s; read it from a file. |
ref.label, ref.chunk | NULL, TRUE | Reuse other chunks’ code. | |
| Child documents | child | NULL | Documents to knit and insert. |
| Engines | engine | 'R' | Language engine. |
engine.path, engine.opts, engine.env | NULL | Executable, options and environment for the engine. | |
| Templates | opts.label | NULL | Apply options saved with opts_template. |
| Extraction | purl | TRUE | Include the chunk when purl() extracts the code. |
| Other | R.options | NULL | R options() set for this chunk only. |
knitr package options
Set with knitr::opts_knit$set() for the whole document:
aliases, base.dir, base.url,
concordance (FALSE), eval.after
(fig.cap, fig.scap, fig.alt),
global.par (FALSE), header,
label.prefix (table = 'tab:'),
latex.options.color, latex.options.graphicx,
latex.tilde, out.format, progress
(TRUE), root.dir, self.contained
(TRUE), unnamed.chunk.label
('unnamed-chunk'), upload.fun (identity),
verbose (FALSE).