R Markdown is a low-overhead way of writing reports which includes R code and the code’s automatically-generated output. It also lets you include nicely-typeset math, hyperlinks, images, and some basic formatting. The goal of this document is to explain, with examples, how to use its most essential features. It is not a comprehensive reference. (See rather http://rmarkdown.rstudio.com.)
This guide assumes that you know at least some R.
This guide lives at http://www.stat.cmu.edu/~cshalizi/rmarkdown/rmarkdown.Rmd. Please see there for the latest version. Corrections and suggestions are welcome.
You are probably used to word processing programs, like Microsoft Word, which employ the “what you see is what you get” (WYSIWYG) principle: you want some words to be printed in italics, and, lo, they’re in italics right there on the screen. You want some to be in a bigger, different font and you just select the font, and so on. This works well enough for n00bs but is not a viable basis for a system of text formatting, because it depends on a particular program (a) knowing what you mean and (b) implementing it well. For several decades, really serious systems for writing have been based on a very different principle, that of marking up text. The essential idea in a mark-up language is that it consists of ordinary text, plus signs which indicate how to change the formatting or meaning of the text. Some mark-up languages, like HTML (Hyper-Text Markup Language) use very obtrusive markup; others, like the language called Markdown, are more subtle. For instance, the last few sentences in Markdown look like this:
For several decades, really serious systems for writing have been based on a
very different principle, that of _marking up_ text. The essential idea in a
**mark-up language** is that it consists of ordinary text, _plus_ signs which
indicate how to change the formatting or meaning of the text. Some mark-up
languages, like HTML (Hyper-Text Markup Language) use very obtrusive markup;
others, like the language called **Markdown**, are more subtle.
Every mark-up language needs to be rendered somehow into a format which actually includes the fancy formatting, images, mathematics, computer code, etc., etc., specified by the mark-up. For HTML, the rendering program is called a “web browswer”. Most computers which know how to work with Markdown at all know how to render it as HTML (which you can then view in a browser), PDF (which you can then view in Acrobat or the like), or Word (which you can then view in the abomination of Redmond).
The advantages of mark-up languages are many: they tend to be more portable across machines, less beholden to particular software companies, and more stable over time than WYSIWYG word processing programs. R Markdown is, in particular, both “free as in beer” (you will never pay a dollar for software to use it) and “free as in speech” (the specification is completely open to all to inspect). Even if you are completely OK with making obeisance to the Abomination of Redmond every time you want to read your own words, the sheer stability of mark-up languages makes them superior for scientific documents.
Markdown is a low-overhead mark-up language invented by John Gruber. There are now many programs for translating documents written in Markdown into documents in HTML, PDF or even Word format (among others). R Markdown is an extension of Markdown to incorporate running code, in R, and including its output in the document. This document look in turn at three aspects of R Markdown: how to include basic formatting; how to include R code and its output; and how to include mathematics.
To write R Markdown, you will need a text editor, a program which lets you read and write plain text files. You will also need R, and the package rmarkdown
(and all the packages it depends on).
If this is your first time using a text editor for something serious, I recommend using R Studio.
Assuming you have the document you’re working on open in the text editor, click the button that says “knit”.
See the render
command in the package rmarkdown
.
If you prefer to render from the command line, the Perl script rmarkdown.pl
accompanying this will do the job. The usage is rmarkdown.pl filename
, and results in the output filename.html
or filename.pdf
, as specified in the file itself. (See below.)
For the most part, text is just text. One advantage of R Markdown is that the vast majority of your document will be stuff you just type as you ordinarily would.
To insert a break between paragraphs, include a single completely blank line.
To force a line break, put two blank
spaces at the end of a line.
To insert a break between paragraphs, include a single completely blank line.
To force a line break, put _two_ blank
spaces at the end of a line.
The character #
at the beginning of a line means that the rest of the line is interpreted as a section header. The number of #
s at the beginning of the line indicates whether it is treated as a section, sub-section, sub-sub-section, etc. of the document. For instance, Basic Formatting in R Markdown
above is preceded by a single #
, but Headers
at the start of this paragraph was preceded by ###
. Do not interrupt these headers by line-breaks.
Text to be italicized goes inside a single set of underscores or asterisks. Text to be boldfaced goes inside a double set of underscores or asterisks.
Text to be _italicized_ goes inside _a single set of underscores_ or *asterisks*. Text to be **boldfaced** goes inside a __double set of underscores__ or **asterisks**.
Set-off quoted paragraphs are indicated by an initial >
:
In fact, all epistemological value of the theory of probability is based on this: that large-scale random phenomena in their collective action create strict, nonrandom regularity. [Gnedenko and Kolmogorov, Limit Distributions for Sums of Independent Random Variables, p. 1]
> In fact, all epistemological value of the theory of probability is based on this: that large-scale random phenomena in their collective action create strict, nonrandom regularity. [Gnedenko and Kolmogorov, _Limit Distributions for Sums of Independent Random Variables_, p. 1]
Text to be printed in a fixed-width font, without further interpretation, goes in paired left-single-quotes, a.k.a. “back-ticks”, without line breaks in your typing. (Thus R
vs. R.) If you want to display multiple lines like this, start them with three back ticks in a row on a line by themselves, and end them the same way:
Text to be printed in a fixed-width font, without further interpretation,
goes in paired left-single-quotes, a.k.a. "back-ticks", without line breaks
in your typing. (Thus `R` vs. R.)
*
(asterisk) character, or a single dash (-
).+
for sub-bullets.Hyperlinks anchored by URLs are easy: just type the URL, as, e.g., http://www.stat.cmu.edu/~cshalizi/rmarkdown/rmarkdown.Rmd to get the source file for this document.
Hyperlinks anchored to text have the anchor in square brackets, then the link in parentheses.
[anchor in square brackets, then the link
in parentheses](http://www.stat.cmu.edu/~cshalizi/rmarkdown/rmarkdown.Rmd)
Images begin with an exclamation mark, then the text to use if the image can’t be displayed, then either the file address of the image (in the same directory as your document) or a URL. Here are two examples, one for an image in the directory and one for a URL.


There doesn’t seem to be a way of re-sizing images using these Markdown commands. Since you are using R Markdown, however, you can use the following hack:
```{r, fig.retina=NULL, out.width=100, echo=FALSE}
knitr::include_graphics("http://apod.nasa.gov/apod/image/1302/ringshexagon_cassini_1016.jpg")
```