Overview

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.

Mark Up, Markdown

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.

Rendering and Editing

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.

Rendering in R Studio

Assuming you have the document you’re working on open in the text editor, click the button that says “knit”.

Rendering in R without using R Studio

See the render command in the package rmarkdown.

Rendering from the command line (Unix-type systems)

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.)

Basic Formatting in R Markdown

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.

Paragraph Breaks and Forced Line Breaks

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.

Headers

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.

Italics, Boldface

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**.

Quotations

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]

Computer Type

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.)

Bullet Lists

  • This is a list marked where items are marked with bullet points.
  • Each item in the list should start with a * (asterisk) character, or a single dash (-).
  • Each item should also be on a new line.
    • Indent lines and begin them with + for sub-bullets.
    • Sub-sub-bullet aren’t really a thing in R Markdown.

Numbered lists

  1. Lines which begin with a numeral (0–9), followed by a period, will usually be interpreted as items in a numbered list.
  2. R Markdown handles the numbering in what it renders automatically.
  3. This can be handy when you lose count or don’t update the numbers yourself when editing. (Look carefully at the .Rmd file for this item.)
    1. Sub-lists of numbered lists, with letters for sub-items, are a thing.
    2. They are however a fragile thing, which you’d better not push too hard.

Title, Author, Date, Output Format, Table of Contents

You can specify things like title, author and date in the header of your R Markdown file. This goes at the very beginning of the file, preceded and followed by lines containing three dashes. Thus the beginning of this file looks like so:

---
title: Using R Markdown for Class Reports
author: CRS
date: First version 7 January 2016, revision of 22 August 2016
---

You can also use the header to tell R Markdown whether you want it to render to HTML (the default), PDF, or something else. To have this turned into PDF, for instance, I’d write

---
title: Using R Markdown for Class Reports
author: CRS
date: First version 7 January 2016, revision of 22 August 2016
output: pdf_document
---

Adding a table of contents is done as an option to the output type.

---
title: Using R Markdown for Class Reports
author: CRS
date: First version 7 January 2016, revision of 22 August 2016
output:
  html_document:
    toc: true
---
  • To create PDF, a program called LaTeX (see below) has to be installed on your computer.
  • Other output formats may be available. See help(render) in the rmarkdown package.
  • There are many, many other formatting options which can be given in the header; see the main R Markdown help files online.