Getting Started with R Markdown

R Markdown is a file format that lets you write narrative text, embed R code, and render the output as a polished document. It is the foundation of reproducible research in R, enabling you to create reports, presentations, dashboards, and even books that automatically update when your data changes.

In this tutorial, you will learn how to create your first R Markdown document, understand its structure, and render it to different output formats.

Installing the Required Packages

R Markdown is part of the RStudio IDE, but you will need to install the rmarkdown package to render documents.

install.packages("rmarkdown")
install.packages("kable")      # For nice tables
install.packages("ggplot2")    # For examples

Creating Your First R Markdown Document

In RStudio, go to File > New File > R Markdown. A dialog will appear where you can choose a title and output format. For now, select “Document” and leave the default output format as HTML.

This creates a new file with default content that demonstrates the key features of R Markdown:

---
title: "My First R Markdown"
author: "Your Name"
date: "2026-03-10"
output: html_document
---

{r setup, include=FALSE}
knitopts::opts_chunk$set(echo = TRUE)

## R Markdown

This is an R Markdown document. When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks.

{r cars}
summary(cars)

## Including Plots

You can also embed plots, for example:

{r pressure, echo=FALSE}
plot(pressure)

Understanding the File Structure

An R Markdown document has three main components:

1. YAML Header

The YAML header sits between the triple dashes --- at the top. It contains metadata like the title, author, date, and output format:

---
title: "My Report"
author: "Jane Doe"
date: "2026-03-10"
output: html_document
---

You can change the output format to pdf_document or word_document to render to PDF or Word. Each format has additional options you can specify.

2. Text Narrative

Regular text is written in Markdown, a lightweight markup language. You can format text with bold, italics, create bullet lists, add links, and structure content with headings:

# Heading 1
## Heading 2
### Heading 3

- Bullet point
- Another point

**Bold text** and *italic text*

3. R Code Chunks

Code chunks are enclosed in triple backticks with {r} after the opening backticks:

# Your R code here
summary(data)

You can name each chunk to help organize your document and make debugging easier. Chunk options control how the code and output appear:

• echo=TRUE: Show the R code (default)
• echo=FALSE: Hide the code, show only output
• include=FALSE: Run the code but hide both code and output
• message=FALSE: Suppress messages from the code
• warning=FALSE: Suppress warnings
• fig.width and fig.height: Control plot dimensions
• fig.cap: Add a caption to plots
• cache=TRUE: Cache chunk results for faster rendering

Global Options

You can set options that apply to all chunks using opts_chunk$set() in a setup chunk at the beginning of your document:

{r setup, include=FALSE}
knit opts::opts_chunk$set(
  echo = FALSE,
  message = FALSE,
  warning = FALSE,
  fig.width = 6,
  fig.height = 4
)

This is useful when you want a consistent look across your entire document.

Working with Figures

R Markdown handles figures automatically. Any plot you create in a code chunk will be automatically included in the rendered output. You can customize figure placement and sizing:

{r pressure-plot, fig.width=8, fig.height=5, fig.cap="Pressure vs Temperature"}
plot(pressure)

The figure will be saved as an image file and embedded in your document. You can reference figures using their chunk names, which is helpful when writing about your visualizations.

Including Data Files

You can read external data files directly in your R Markdown document:

{r read-data}
data <- read.csv("data.csv")
summary(data)

This makes R Markdown particularly powerful for data analysis workflows, where your report automatically reflects the current state of your data.

Rendering Your Document

To render an R Markdown document:

1. Click the Knit button in RStudio, or
2. Use the render() function in R:

rmarkdown::render("my-document.Rmd")

R Markdown will execute each code chunk in sequence, insert the output into the document, and then convert the entire file to your chosen output format.

Adding a Table

The kable() function from the knitr package creates nice-looking tables:

library(ggplot2)
library(kable)

mtcars[1:5, 1:4] |> 
  kable(caption = "First five rows of mtcars")

Embedding Inline Code

You can embed R code directly in your narrative text using `r code`. This is useful for inserting calculated values:

The dataset has `r nrow(mtcars)` observations.

This renders as: The dataset has 32 observations.

Next Steps

Now that you have created your first R Markdown document, you can explore:

• Different output formats: Try output: pdf_document or output: word_document
• Parameterised reports: Create reports that accept inputs using the params field in the YAML
• R Notebooks: Use output: html_notebook for an interactive notebook experience

Continue to the next tutorial in this series to learn about Getting Started with Quarto.