Translations (PDF)
- Dutch
- German
- Italian
- Japanese
- Korean
- Spanish
- Turkish
- Vietnamese
What is rmarkdown?
- .Rmd files: Develop your code and ideas side-by-side in a single document. Run code as individual chunks or as an entire document.
- Dynamic Documents: Knit together plots, tables, and results with narrative text. Render to a variety of formats like HTML, PDF, MS Word, or MS PowerPoint.
- Reproducible Research: Upload, link to, or attach your report to share. Anyone can read or run your code to reproduce your work.
Workflow
Open a new .Rmd file in the RStudio IDE by going to File > New File > R Markdown.
Embed code in chunks. Run code by line, by chunk, or all at once.
Write text and add tables, figures, images, and citations. Format with Markdown syntax or the RStudio Visual Markdown Editor.
Set output format(s) and options in the YAML header. Customize themes or add parameters to execute or add interactivity with Shiny.
Save and render the whole document. Knit periodically to preview your work as you write.
Share your work!
Source Editor
Expand to read about the features in the Source Editor
Features within the Source Editor
- New File
- Embed Code
- Write Text
- Set Output Format(s) and Options
- Save and Render
- Share
- Set preview location
- Insert code chunk
- Go to code chunk
- Run code chunk(s)
- Show outline
- Modify chunk options
- Run all previous chunks
- Run current chunk
- Switch to visual editor
Visual Editor
Expand to read about the features in the Visual Editor
Features within the Visual Editor
- Insert citations
- Style options
- Add/edit attributes
- Switch to source editor
Rendered Output
Expand to read about the features in the Rendered Output Window
Features within the Rendered Output Window
- File path to output document
- Find in document
- Publish to rpubs.com, shinyapps.io, Posit Connect
- Reload document
Embed Code With knitr
Code Chunks
Surround code chunks with ```{r}
and ```
or use the Insert Code Chunk button. Add a chunk label and/or chunk options inside the curly braces after r
.
```{r chunk-label, include = FALSE}```
Set Global Options
Set options for the entire document in the first chunk.
```{r include = FALSE}knitr::opts_chunk$set(message = FALSE)```
Inline Code
Insert `r <code>`
into text sections. Code is evaluated at render and results appear as text.
The markdown text
Built with `r getRversion()`
will render as “Built with 4.4.0” in the output file.
Chunk Options
Option | Default | Effects |
---|---|---|
echo | TRUE | display code in output document |
error | FALSE | TRUE (display error messages in doc), FALSE (stop render when error occurs) |
eval | TRUE | run code in chunk |
include | TRUE | include chunk in doc after running |
message | TRUE | display code messages in document |
warning | TRUE | display code warnings in document |
results | "markup" | "asis" (pass through results), "hide" (don’t display results), "hold" (put all results below all code) |
fig.align | "default" | "left" , "right" , or "center" |
fig.alt | NULL | alt text for a figure |
fig.cap | NULL | figure caption as a character string |
fig.path | "figure/" | prefix for generating file paths |
fig.width & fig.height | 7 | plot dimensions in inches |
out.width | rescales output width, e.g."75%" , "300px" | |
collapse | FALSE | collapse all sources & output into a single block |
comment | "##" | prefix for each line of results |
child | NULL | file(s) to knit and then include |
purl | TRUE | include or exclude a code chunk when extracting source code with knitr::purl() |
See more options and defaults by running str(knitr::opts_chunk$get())
.
Insert Citations
Create citations from a bibliography file, a Zotero library, or from DOI references.
Build Your Bibliography
Add BibTex or CSL bibliographies to the YAML header.
---title: "My Document"bibliography: references.biblink-citations: TRUE---
If Zotero is installed locally, your main library will automatically be available.
Add citations by DOI by searching “from DOI” in the Insert Citation dialog.
Insert Citations
- Access the Insert Citations dialog in the Visual Editor by clicking the @ symbol in the toolbar or by clicking Insert > Citation.
- Add citations with markdown syntax by typing
[@cite]
or@cite
.
Insert Tables
Output data frames as tables using kable(data, caption)
.
```{r}data <- faithful[1:4,]knitr::kable(data, caption = "Tables with kable")```
Other table packages include flextable, gt, and kableExtra.
Write With Markdown
The syntax on the left renders as the output on the right.
| Plain text. | ||||||||||||||||
| End a line with two spaces to start a new paragraph. | ||||||||||||||||
| Also end a line with a backslash to make a new line. | ||||||||||||||||
| italics and bold | ||||||||||||||||
| superscript2 /subscript2 | ||||||||||||||||
| |||||||||||||||||
| escaped: * _ \ | ||||||||||||||||
| en dash: –, em dash: — | ||||||||||||||||
| |||||||||||||||||
| Header 2 | ||||||||||||||||
| … | ||||||||||||||||
| Header 6 | ||||||||||||||||
|
| ||||||||||||||||
|
| ||||||||||||||||
| https://posit.co/ | ||||||||||||||||
| This is a link. | ||||||||||||||||
| This is another link. | ||||||||||||||||
| |||||||||||||||||
| verbatim code | ||||||||||||||||
|
| ||||||||||||||||
|
| ||||||||||||||||
| equation: \(e^{i \pi} + 1 = 0\) | ||||||||||||||||
| equation block: \[E = mc^{2}\] | ||||||||||||||||
| horizontal rule: | ||||||||||||||||
|
| ||||||||||||||||
HTML Tabsets
| Results |
Set Output Formats and Their Options in YAML
Use the document’s YAML header to set an output format and customize it with output options. Indent format 2 characters, indent options 4 characters.
---title: "My Document"author: "Author Name"output: html_document: toc: true toc-location: left---
Output Format Table
Output Format | Creates |
---|---|
html_document | .html |
pdf_document 1 | |
word_document | Microsoft Word (.docx) |
powerpoint_presentation | Microsoft PowerPoint (.pptx) |
odt_document | OpenDocument Text |
rtf_document | Rich Text Format |
md_document | Markdown |
github_document | Markdown for Github |
ioslides_presentations | ioslides HTML slides |
slidy_presentation | Slidy HTML slides |
beamer_presentation 2 | Beamer slides |
Also see flexdashboard, bookdown, distill, and blogdown.
Output Options Table
Important Options | Description | HTML | MS Word | MS PPT | |
---|---|---|---|---|---|
anchor_sections | Show section anchors on mouse hover (TRUE or FALSE) | X | |||
citation_package | The LaTeX package to process citations (“default”, “natbib”, biblatex”) | ||||
code_download | Give readers an option to download the .Rmd source code (TRUE or FALSE) | X | |||
code_folding | Let readers toggle the display of R code (“none”, “hide”, or “show”) | X | |||
css | CSS or SCSS file to use to style the document (e.g.“style.css”) | X | |||
dev | Graphics device to use for figure output (e.g.“png”, “pdf”) | X | X | ||
df_print | Method for printing data frames (“default”, “kable”, “tibble”, “paged”) | X | X | X | X |
fig_caption | Should figures be rendered with captions (TRUE or FALSE) | X | X | X | X |
highlight | Syntax highlighting (“tango”, “pygments”, “kate”, “zenburn”, “textmate”) | X | X | X | |
includes | File of content to place in doc (“in_header”, “before_body”, “after_body”) | X | X | ||
keep_md | Keep the Markdown .md file generated by knitting (TRUE or FALSE) | X | X | X | X |
keep_tex | Keep the intermediate TEX file used to convert to PDF (TRUE or FALSE) | X | |||
latex_engine | LaTeX engine for producing PDF output (“pdflatex”, “xelatex”, or “lualatex”) | X | |||
reference_docx/_doc | docx/pptx file containing styles to copy in the output (e.g.“file.docx”, “file.pptx”) | X | X | ||
theme | Theme options (see Bootswatch and Custom Themes below) | X | |||
toc | Add a table of contents at start of document (TRUE or FALSE) | X | X | X | X |
toc_depth | The lowest level of headings to add to table of contents (e.g.2, 3) | X | X | X | X |
toc_float | Float the table of contents to the left of the main document content (TRUE or FALSE) | X |
Use ?<output_format>
to see all of a format’s options, e.g.?html_document
More Header Options
Parameters
Parameterize your documents to ruse with new inputs (e.g.data, values, etc.).
Add parameters in the header as sub-values of
params
.---params: state: "hawaii"---
Call parameters in code using
params$name
.```{r}data <- df[,params$state]summary(data)```
Set parameters with Knit with Parameters or the params argument of
render()
.
Reusable Templates
Create a new package with an inst/rmarkdown/templates directory.
Add a folder containing template.yaml (below) and skeleton.Rmd (template contents).
---name: "My Template"---
Install the package to access template by going to File > New R Markdown > From Template.
Bootswatch Themes
Customize HTML documents with Bootswatch themes from the bslib package using the theme output option. Use bslib::bootswatch_themes()
to list available themes.
---title: "My Document"author: "Author Name"output: html_document: theme: bootswatch: solar---
Custom Themes
Customize individual HTML elements using bslib variables. Use ?bs_theme
to see more variables.
---output: html_document: theme: bg: "#121212" fg: "#E4E4E4" base_font: google: "Prompt"---
More on bslib at https://pkgs.rstudio.com/bslib/.
Styling With CSS and SCSS
Add CSS and SCSS to your documents by adding a path to a file with the css option in the YAML header.
---title: "My Document"author: "Author Name"output: html_document: css: "style.css"---
Apply CSS styling by writing HTML tags directly or:
Use markdown to apply style attributes inline.
Bracketed Span
A [green]{.my-color} word.
will render as “A green word.”Fenced Div
:::{.my-color}All of these wordsare green:::
will render as
All of these words
are green.
Use the Visual Editor. Go to Format > Div/Span and add CSS styling directly with Edit Attributes.
Interactivity
Turn your report into an interactive Shiny document in 4 steps:
Add
runtime: shiny
to the YAML header.---output: html_documentruntime: shiny---
Call Shiny input functions to embed input objects.
Call Shiny output functions to embed reactive output.
```{r echo = FALSE}numericInput("n", "How many cars?", 5)renderTable({ head(cars, input$n)})```
Render with
rmarkdown::run()
or click Run Document in RStudio IDE.
Also see Shiny Prerendered for better performance. https://rmarkdown.rstudio.com/authoring_shiny_prerendered.
Embed a complete Shiny app into your document with shiny::shinyAppDir()
. More at https://bookdown.org/yihui/rmarkdown/shiny-embedded.html.
Render
When you render a document, rmarkdown:
- Runs the code and embeds results and text into an .md file with knitr.
- Converts the .md file into the output format with Pandoc.
Save, then Knit to preview the document output. The resulting HTML/PDF/MS Word/etc. document will be created and saved in the same directory as the .Rmd file.
Use rmarkdown::render()
to render/knit in the R console. See ?render
for available options.
Footnotes
PDFs and Beamer slides require LaTeX, use
tinytex::install_tinytex()
.↩︎PDFs and Beamer slides require LaTeX, use
tinytex::install_tinytex()
.↩︎