Markdown in R Studio
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.
Note
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"
output:
html_document:
toc: true
theme: united
pdf_document:
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' author: - 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);
}
Lists
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.
Note
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)
Tables
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
rows.
-------------------------------------------------------------
Tables can also be given a label that either proceeds or follows them:
Table: Demonstration of simple table syntax.
Note
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.