Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
Who this is for: researchers and analysts who write analysis reports in R and need a copyable reference for installing the rmarkdown package, rendering a document, setting chunk options and choosing an output format. Unlike the PDF cheat sheets, everything here is plain text you can copy and search.
Short answer: R Markdown (the rmarkdown CRAN package) converts a document that mixes Markdown text and R code chunks into HTML, PDF, Word and other formats. Install it with install.packages("rmarkdown"), then produce output with rmarkdown::render("file.Rmd") or the Knit button in RStudio.
What R Markdown is used for in research
CRAN describes the package as converting R Markdown documents “into a variety of formats”. In research practice that means one source file holds the narrative, the code and the results, so a report can be regenerated when the data change. Documenting such a project is covered in the CASRAI guide to README files. The output formats listed on the R Markdown site include HTML documents and notebooks, PDF, Word, ODT, RTF and Markdown; slide formats (ioslides, reveal.js, Slidy, Beamer, PowerPoint); and dashboards (flexdashboard), Tufte handouts, books, package vignettes and GitHub documents. For slides see R presentations.
How to install or access it
- Install R, then in the R console run
install.packages("rmarkdown"). This installs the package from CRAN, as in Lesson 1 of the R Markdown site. - Check that Pandoc is available. The CRAN page lists
Pandoc (>= 2.8)under SystemRequirements. If you work in RStudio, see how to use RStudio. - Load it with
library(rmarkdown), or call functions asrmarkdown::render().
As checked on 2026-11-08, the CRAN page shows rmarkdown version 2.32, published 2026-09-01. CRAN lists two vignettes: “Learn R Markdown” and “Lua filters in R Markdown”.
Step-by-step task: write and render a parameterised report
This sequence uses only features documented on the R Markdown site and in the knitr options reference. The file name and parameter value are placeholders.
- Create the .Rmd file. It holds a YAML header between
---lines, Markdown text, and code chunks that start with```{r}. Theoutputfield in the YAML header sets the default output format. - Add chunk options in the chunk header, for example
```{r, echo = FALSE}to hide the code but show its output. The options table below lists the defaults. - Put results in the text with inline code. The inline syntax is a backtick, the letter
r, a space, an R expression, and a closing backtick, so a sentence can report a computed value directly (R Markdown Lesson 4). - Declare parameters in the YAML header with a
paramsfield. Inside the document they are read asparams$<name>; theparamsobject is a read-only list (Lesson 6). - Render. In RStudio click Knit; the button uses the first format listed under
output, and the dropdown offers the others. From the console runrender("report.Rmd"). - Choose a format or parameter value at render time:
render("report.Rmd", output_format = "word_document")andrender("report.Rmd", params = list(data = "aleutians")). In RStudio, “Knit with Parameters” in the knit dropdown does the same for parameters.
Format-specific arguments go as sub-values of the format in the output field; see ?html_document for the HTML options.
Chunk options quick reference
Defaults below are from the knitr options reference (yihui.org/knitr/options), read 2026-11-08.
| Option | Default | What it does |
|---|---|---|
echo |
TRUE | Show the source code in the output |
eval |
TRUE | Run the code in the chunk |
include |
TRUE | When FALSE, the code runs and plots are saved, but nothing from the chunk is shown |
results |
‘markup’ | How text output is handled: markup, asis, hold or hide |
message |
TRUE | Show messages from the code |
warning |
TRUE | Show warnings; NA sends them to the console instead |
fig.width, fig.height |
7, 7 (inches) | Size of plots |
fig.cap |
NULL | Figure caption |
cache |
FALSE | When TRUE, unchanged chunks are skipped on later runs |
Output and how to read it
With the default chunk options the rendered document shows each chunk’s code, its printed output, and any messages and warnings, in order. Setting echo = FALSE leaves only results, which suits a report to collaborators; read the messages and warnings before switching them off, since both default to TRUE. Citations in R Markdown go through Pandoc; see citations in Quarto, R Markdown and Pandoc.
Troubleshooting
- Rendering fails because Pandoc is missing or old. The package lists Pandoc 2.8 or later as a system requirement (CRAN, checked 2026-11-08).
- A chunk’s code does not appear, or does not run. Check
echoandeval; the first hides code, the second stops it executing. - A plot is missing from the output. A chunk with
include = FALSEruns and saves plots but shows nothing. - A slow report re-runs everything.
cache = TRUEmakes knitr skip unchanged chunks.
Free alternatives
| Tool | Relationship to R Markdown |
|---|---|
| Quarto | Multi-language publishing system that uses Knitr to run R code and renders most R Markdown documents unmodified; chunk options are written as #| comment lines and the YAML key is format rather than output. The Quarto FAQ states R Markdown is not going away. Details: Quarto vs R Markdown. |
FAQ
How do I create a Word document from an .Rmd file?
Run render("file.Rmd", output_format = "word_document") or list word_document under output in the YAML header.
What does the Knit button do?
In RStudio it renders using the first format listed under output; the dropdown beside it offers the other formats.
Should I switch to Quarto?
Not necessarily; the Quarto FAQ says R Markdown is not going away. See the comparison linked above.
Sources
- CRAN, rmarkdown package page: https://cran.r-project.org/web/packages/rmarkdown/index.html (read 2026-11-08)
- R Markdown site, Lessons 1, 4, 6 and 9: https://rmarkdown.rstudio.com/lesson-1.html (read 2026-11-08)
- knitr chunk options: https://yihui.org/knitr/options/ (read 2026-11-08)







