A note from the authors: Some of the information and instructions in this book are now out of date because of changes to Hugo and the blogdown package. If you have suggestions for improving this book, please file an issue in our GitHub repository. Thanks for your patience while we work to update the book, and please stay tuned for the revised version!
In the meantime, you can find an introduction to the changes and new features in the v1.0 release blog post and this "Up & running with blogdown in 2021" blog post.
— Yihui, Amber, & Alison
A R Markdown
R Markdown (Allaire et al. 2023) is a plain-text document format consisting of two components: R (or other computing languages) and Markdown. Markdown makes it easy for authors to write a document due to its simple syntax. Program code (such as R code) can be embedded in a source Markdown document to generate an output document directly: when compiling the source document, the program code will be executed and its output will be intermingled with the Markdown text.
R Markdown files usually use the filename extension .Rmd. Below is a minimal example:
---
title: A Simple Linear Regression
author: Yihui Xie
---
We build a linear regression below.
```{r}
fit = lm(dist ~ speed, data = cars)
b = coef(summary(fit))
plot(fit)
```
The slope of the regression is `r b[2, 1]`.Such a document can be compiled using the function rmarkdown::render(), or equivalently, by clicking the Knit button in RStudio. Under the hood, an R Markdown document is first compiled to Markdown through knitr (Xie 2023b), which executes all program code in the document. Then the Markdown output document is compiled to the final output document through Pandoc, such as an HTML page, a PDF document, a Word document, and so on. It is important to know this two-step process, otherwise you may not know which package documentation to look up when you have questions. Basically, for anything related to the (R) code chunks, consult the knitr documentation (https://yihui.org/knitr/); for anything related to Markdown, consult the Pandoc documentation (https://pandoc.org).
An R Markdown document typically consists of YAML metadata (optional) and the document body. YAML metadata are written between a pair of --- to set some attributes of the document, such as the title, author, and date, etc. In the document body, you can mix code chunks and narratives. A code block starts with a chunk header ```{r} and ends with ```. There are many possible chunk options that you can set in the chunk header to control the output, e.g., you can set the figure height to 4 inches using ```{r fig.height=4}. For all possible chunk options, see https://yihui.org/knitr/options/.
Pandoc supports a large variety of output document formats. For blogdown, the output format is set to HTML (blogdown::html_page), since a website typically consists of HTML pages. If you want other formats, please see Section 2.7. To create an R Markdown post for blogdown, it is recommended that you use the RStudio “New Post” (Figure 1.7) or the function blogdown::new_post(), instead of the RStudio menu File -> New File -> R Markdown.
You are strongly recommended to go through the documentation of knitr chunk options and Pandoc’s manual at least once to have an idea of all possibilities. The basics of Markdown are simple enough, but there are many less well-known features in Pandoc’s Markdown, too. As we mentioned in Section 1.6, blogdown’s output format is based on bookdown (Xie 2023a), which contains several other Markdown extensions, such as numbered equations and theorem environments, and you need to read Chapter 2 of the bookdown book (Xie 2016) to learn more about these features.
You can find an R Markdown cheat sheet and a reference guide at https://posit.co/resources/cheatsheets/, which can be handy after you are more familiar with R Markdown.
With R Markdown, you only need to maintain the source documents; all output pages can be automatically generated from source documents. This makes it much easier to maintain a website, especially when the website is related to data analysis or statistical computing and graphics. When the source code is updated (e.g., the model or data is changed), your web pages can be updated accordingly and automatically. There is no need to run the code separately and cut-and-paste again. Besides the convenience, you gain reproducibility at the same time.