Markdown in R Studio

What Markdown markup is allowed.

If you're doing reproducbility in R Studio, you're probably using knitr. And if you're using knitr, you're probably using Markdown. Unfortunately, due to the lack of a standard for Markdown (and the subsequent proliferation of various flavours and extensions), it's sometimes not clear what syntax is available to you. Consequently, you tend to write in the lowest common denominator / most common syntax.

This is an exploration of what markup is available should you use Markdown in R Studio, based on the source distribution, documentation and some experiments. I'm not trying to explain all of Markdown, just the oddities and extras you'll find in R Studio.


You can use reStructured Text instead of Markdown, it's more powerful and has more features, but Markdown is the first class citizen in the R Studio universe and you'll always be fighting the system in some way.

Technical details

R Studio v0.98 on Mac OSX 10.9, April 2015.

General issues

R Studio Markdown (henceforth RSMarkdown) is an R package that is based on pandoc. While it is possible to install extensions for the package, it's not clear to me how to get RSMarkdown to use these extensions.

Markdown is generally focused on HTML as an output. RSMarkdown is more general and allows other and mutliple output formats.

Where a block of text must be indented, that indentation is a tab or at least 4 spaces.

Metadata & headers

RSMarkdown explicitly allows for metadata, which may define title and output format. Multiple outputs can be defined, with variables that apply just in those contexts:

title: "Sample Document"
    toc: true
    theme: united
    toc: true
    highlight: zenburn

Possible output formats are:

  • html_document
  • pdf_document
  • word_document
  • md_document
  • beamer_presentation
  • ioslides_presentation
  • slidy_presentation

This style of metadata is in fact YAML and can include other fields:

title:  'This is the title: it contains a colon'
- name: Author One
  affiliation: University of Somewhere
- name: Author Two
  affiliation: University of Nowhere
tags: [nothing, nothingness]
abstract: |
  This is the abstract.

  It consists of two paragraphs.

Obscurely, RSMarkdown includes a second type of metadata, where the intial lines of a file can include 3 lines beginning with percent signs, giving bibliographic information:

% title
% author(s)
% date

The order and number of lines are fixed. It is unclear whether R Studio does anything with this info.

Two styles of headers are permitted, covering slightly different levels of headings:

A level-one header

A level-two header

## A level-two header

### A level-three header

#### etcetera

"Leading hash" style headers can have matching trailing hashes, e.g. ## FOO ##, which is arguably more readable.

Text styling

Strike-through text is flanked with double-tildes:

This ~~is deleted text.~~

Superscripts are flanked with the "hat" symbol, subscripts are flanked with a single tilde:

2^10^ is 1024, H~2~O is a liquid.

Verbatim / literal text is placed inside backticks:

What is the difference between `>>=` and `>>`?

Quotes & code blocks

Quotes are precded with > marks. Only the first line need have one if subsequent lines are flush against the left margin:

> This is a block quote. This
> paragraph has two lines.

> This is a block quote. This
paragraph has two lines.

Literal quote blocks preserve linebreaks, such as you might want to do for addresses or for poetry. This are preceded with vertical bars |:

| 200 Main St.
| Berkeley, CA 94718

Code blocks are "fenced" with lines of 3 or more tildes, or indented:

if (a > 3) {
 moveShip(5 * gravity, DOWN);

   if (a > 3) {
     moveShip(5 * gravity, DOWN);


Definition lists can be used, with the initial definition line preceded with : and subsequent lines at the same depth. These lists must be indented:

Term 1

:  Definition 1

Term 2

:  Definition 2

   Third paragraph of definition 2.


I've had a lot of trouble with definition lists, even after reading the spec and documentation. Regardless of what is written elsewhere, it seems like the whole list has to be indented and the definition has to be at the same level of indentation as the term.

Numbered lists can be constructed with (@):

(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2)


You can do tables in RSMarkdown. Lord, can you do tables. There's multiple ways to do them, but I'll drop a few simple examples here, from which the general form can be inferred. Note that no header is required and horizontal lines are fairly freeform:

 Right     Left     Center     Default
-------    ------ ----------   -------
    12     12        12           12
   123     123       123          123
     1     1         1            1

-------  ------  ----------  -------
     12  12           12          12
    123  123         123         123
      1  1            1            1
-------  ------  ----------  -------

Centered    Default           Right  Left
 Header     Aligned         Aligned  Aligned
----------- ------- ---------------  ------------------------
  First      row               12.0  Example of a row that
                                     spans multiple lines.

 Second      row                5.0  Here's another one. Note
                                     the blank line between

Tables can also be given a label that either proceeds or follows them:

Table:  Demonstration of simple table syntax.


Tables are tremendously fiddly. Get even a single character out of the column and RSMarkdown will foul it up. I've even had cases where a seemingly valid table won't format correctly for unclear reasons.