Appearance
A reproducible report in R Markdown is a single document that mixes your narrative prose with the R code that produces every figure, table and number, so the whole thing regenerates from your data with one click. Instead of pasting results into Word and hoping they stay current, you write text and code together in a .Rmd file and knit it to HTML, PDF or Word. Change the data, re-knit, and the report updates itself.
What is an R Markdown document made of?
Three ingredients sit in one plain-text file:
- A YAML header at the top, between
---lines, setting title, author and output format. - Markdown prose for your argument, written in normal text.
- Code chunks delimited by triple backticks with
{r}, holding the R that computes results.
A minimal example:
markdown
---
title: "Burials in St Mary's Parish, 1700-1799"
author: "Elara Reed"
output: html_document
---
The parish register records a marked rise in burials after 1740.
```{r}
library(tidyverse)
burials <- read_csv("data/burials.csv")
mean(burials$count)
```How does knitting make a report reproducible?
When you press Knit (or run rmarkdown::render()), R executes every chunk top to bottom in order, captures the output, and weaves it into the final document. The crucial point: the number in your report is the computed result, not a transcription. If burials.csv gains a new year, re-knitting updates the mean, the chart and any inline figure automatically. Stale pasted numbers, the bane of long humanities projects, simply cannot occur.
How do you put a live number in a sentence?
Inline code lets a statistic flow into prose and stay correct. Inside your text you write a backtick-delimited r expression, and on knitting it is replaced by the value:
markdown
The register lists `r nrow(burials)` burial events in total.After knitting this reads, for example, "The register lists 1,284 burial events in total" and that figure recomputes every time.
What do chunk options control?
Each chunk can take options that change its behaviour. The most useful for humanities reports:
| Option | Effect |
|---|---|
echo=FALSE | Hide the code, show only its output |
eval=FALSE | Show the code but do not run it |
message=FALSE | Suppress package loading chatter |
fig.cap="..." | Add a caption to a figure |
cache=TRUE | Reuse results for slow chunks |
For a report aimed at general readers, set echo=FALSE so they see clean figures, not R syntax. For a methods appendix, leave echo=TRUE so reviewers can audit the analysis.
Which output format should a beginner pick?
Start with html_document: it needs no extra software, renders fast, and supports interactive tables. Move to PDF only when you need print or submission, which requires TinyTeX once:
r
install.packages("tinytex")
tinytex::install_tinytex()Word output (word_document) is handy when an editor demands track-changes, though it sacrifices some formatting control.
How do you make sure it runs elsewhere?
Three habits make a report portable:
- Knit from a clean session. In RStudio, the Knit button already does this, which is why a script that "works for me" can still fail to knit.
- Use project-relative paths with
here::here("data", "burials.csv"), neverC:/Users/you/.... - Record versions with
renv::snapshot()so a collaborator can restore the same packages.
If it knits cleanly from a fresh session with these in place, it will almost always run on a colleague's machine too.
Key Takeaways
- An
.Rmdfile combines YAML, Markdown prose and runnable code chunks. - Knitting recomputes every result, so reports never go stale.
- Inline
rexpressions embed live, self-updating numbers in sentences. - Chunk options like
echoandfig.capcontrol visibility and captions. - Start with HTML output; add TinyTeX only when you need PDF.
- Knit from a clean session, use
herefor paths, andrenvfor versions. - The same concepts transfer almost unchanged to Quarto.
Frequently Asked Questions
What is the difference between R Markdown and Quarto?
Quarto is the next-generation successor to R Markdown from the same team, with broader language support and a cleaner publishing system. R Markdown still works and is widely used; the concepts in this guide carry over almost unchanged to Quarto.
Why is a knitted report more reproducible than copy-pasting numbers?
Because the figures, tables and statistics are computed from your data every time the document is knitted. If the data or code changes, the report updates automatically, so there is no risk of a stale pasted number contradicting the analysis.
Do I need to know LaTeX to make a PDF?
No. R Markdown renders to PDF through LaTeX, but you can install TinyTeX with tinytex::install_tinytex() once and never touch LaTeX directly. HTML output needs nothing extra at all.
What are code chunk options used for?
They control how each block behaves, such as echo to show or hide code, eval to run it or not, and fig.cap for figure captions. They let you keep code visible for reviewers or hidden for general readers.
How do I make sure the report runs on someone else's machine?
Knit in a fresh R session, use project-relative paths with the here package, and record package versions with renv. If it knits from a clean session, it will usually run elsewhere.