R Markdown: Reproducible Reports

R Markdown is a file format that lets you write documents containing live R code. When you render the document, R executes the code and embeds the results directly into the output. This approach is the foundation of reproducible research—you keep your analysis, visualizations, and conclusions in a single file that anyone can re-run.

This guide covers the basics of R Markdown. By the end, you will know how to create a document, add code chunks, format text, and render it to HTML or PDF.

How R Markdown Works

An R Markdown file has the extension .Rmd. It contains three parts:

1. YAML header — metadata at the top, between --- lines
2. Markdown text — regular text with formatting
3. Code chunks — R code blocks that get executed

When you click the Knit button in RStudio, the rmarkdown package processes the file. First, knit runs each code chunk and captures the output. Then, render converts the markdown to your chosen output format. The result is a clean document with your text, code, and results together.

Your First R Markdown Document

Create a new R Markdown file in RStudio through File > New File > R Markdown. For now, accept the default settings. Your file will look like this:

---
title: "My First Report"
author: "Your Name"
date: "2026-03-11"
output: html_document
---

Below the header is where you write your content. Delete everything after the header and replace it with this simple example:

---
title: "Sample Report"
output: html_document
---

## Introduction

This is my first R Markdown document. It demonstrates how text and code work together.

## Basic Math

R can perform calculations inline. For example, 2 + 2 equals `r 2 + 2`.

## Code Chunk

```{r}
# This is a code chunk
summary(cars)

The output from summary(cars) will appear in your rendered document.

Save this as first_report.Rmd and click Knit. You will get an HTML document with the calculation and summary table embedded.

Adding and Configuring Code Chunks

Code chunks are the engine of R Markdown. You insert them with the keyboard shortcut Ctrl+Alt+I (Windows/Linux) or Cmd+Option+I (Mac).

A code chunk looks like this:

# Your R code here
mean(cars$speed)

You can customize each chunk with options placed after {r}:

Option	What it does
echo=FALSE	Hide the code, show only results
include=FALSE	Run the code but hide both code and output
results='hide'	Show code but hide output
message=FALSE	Suppress messages
warning=FALSE	Suppress warnings
fig.width=6	Set figure width

This chunk hides the code but shows a plot:

plot(cars$speed, cars$dist, 
     xlab = "Speed", 
     ylab = "Distance",
     main = "Speed vs Stopping Distance")

Inline Code

You do not always need a full code chunk. Use inline code to insert single values into your text. Wrap R expressions in backticks with r in front:

The average speed in the cars dataset is r mean(cars$speed) mph.

When rendered, this becomes “The average speed in the cars dataset is 15.4 mph.” The number updates automatically if your data changes.

Creating Tables

The knit package includes kable() for creating formatted tables. Load it in a chunk:

library(knitr)
kable(head(cars, 5), caption = "First five rows of the cars dataset")

This produces a nicely formatted HTML table. For more styling, explore the kableExtra package.

Output Formats

The YAML header controls your output format. Common options include:

HTML document:

output: html_document

PDF document:

output: pdf_document

Microsoft Word:

output: word_document

You can also add options to customize the output:

---
title: "My Report"
output:
  html_document:
    toc: true
    theme: united
    highlight: tango
---

toc: true adds a table of contents. theme changes the visual style. highlight controls code syntax coloring.

Rendering from the Console

You do not need RStudio to render documents. Use the render() function:

rmarkdown::render("first_report.Rmd", 
                   output_format = "html_document")

This is useful when automating report generation in scripts or pipelines.

Common Problems

Packages missing: Install the required packages first:

install.packages(c("rmarkdown", "knit"))

PDF fails: Rendering to PDF requires a LaTeX installation. The tinytex package provides a lightweight solution:

install.packages("tinytex")
tinytex::install_tinytex()

Code does not run: Check that your R code is inside a valid chunk marked with ```{r}. The backticks must be on their own lines.

What Comes Next

You have learned the basics of R Markdown. From here, explore these areas:

• Parameterized reports — create documents that accept different inputs each time you render
• R Markdown notebooks — interact with chunks individually in RStudio
• Bookdown — build multi-page books and long-form documents
• Quarto — the next generation of R Markdown with broader language support

R Markdown connects your analysis to your written conclusions. When your data updates, re-knitting the document updates everything.

Written

• File: sites/rguides/src/content/guides/r-markdown-guide.md
• Words: ~850
• Read time: 8 min
• Topics covered: R Markdown basics, code chunks, inline code, tables, output formats, rendering
• Verified via: rmarkdown.rstudio.com, web search
• Unverified items: none