Basic RMarkdown

RMarkdown is a great tool for creating simple html documents to publish your work on the internet and to display interactive graphics. During this tutorial, I will cover everything from creating a simple page that you might use for a homework assignment to creating the skeleton of a complete website. This tutorial, and all of the content on my website, was created using RMarkdown.

Why RMarkdown?

Websites are written in HTML but HTML is a little tedious to write because it relies on nested tags to specify different kinds of objects. Markdown is a standardized language for compiling simple documents that reduce the tediousnss of HTML and reduce the chance of syntax errors. RMarkdown is the implementation of this language for RStudio that facilitates the integration of R code chunks using knitr, which is covered in my introdution to Sweave tutorial here.

RMarkdown is also the language you use to create professional looking Reveal.JS presentations, which I have a tutorial for here.

Getting started

Let’s make a new RMarkdown document, everything you need has already been built into RStudio with a nice interface

  1. Go to: File, New File, R Markdown

  2. Give it a title and your name

  3. Leave these settings unchanged: Document, HTML

  4. Save your file in a folder somewhere.

Now you have an RMarkdown file (.Rmd) that will compile itself into an HTML document when you hit “Knit HTML” in the option bar right above the source window.

If you want a PDF that’s maybe a little easier to distibute you can change the output to a PDF file by hitting the down arrow by “Knit HTML” and selecting “Knit PDF” although mine is not working for this example right now.

Syntax

The RMarkdown syntax is covered in more depth in this official online tutorial but I will summarize the points here and clarify a few portions with are unclear. Topic that they cover that I’m going to skip include: adding emphasis, inline code, links, images, block quotes, latex equations, page breaks, and tables. Some more advanced topics, including Tabbed Sections, adding CSS classes and ids, and Figure Options are covered on a different official page here.

Headings

You specify a heading depth by starting a line with #

  • # signifies a Level 1 Heading

  • ## signifies a Level 2 Heading

  • ###, no surprise, signifies a Level 3 Heading

These will show up as blue in your RMarkdown document code.

Lists

Create bulleted lists with a blank line followed by a line starting with an * ( or - ) for Level 1, and a <tab> + for Level 2, that’s a tab indent and then a +. Each bullet must be preceeded with a blank line for it to be recognized as a bullet instead of the character.

  • List Item

  • List Item 2

    • sub-bullet

There will not be special color for the bullets.

Create numbered lists with numbers followed by a period and a space. Number’s don’t have to have a blank line before them. Numbering will stay sequential no matter what number you enter.

  1. Numbered Item 1

  2. Numbered Item 3

Escaping

Sometimes you don’t want your #s to be headings. There are two easy ways to escape these commands.

  • Use a backlash \ to escape them

  • Or wrap them in back-ticks `#` which also highlights them

Code Chunks

But you’re not using RMarkdown just for type setting, you probably want to incorporate some code.

R Code Chunks

Create an R code area by starting a line with ```{r} and end a code area with ```, these are back-ticks, to the left of the number 1 key.

\```{r}
Put your R code here
\'``

Use the normal knitr code chunk commands to change evaluation, output, highlighting, caching, etc. You can also incorporate code inline if you want a number that automatically updates. Follow this link for knitr options.

You can make code boxes where nothing executes by removing the {r} bit.

HTML Code Chunks

You can also incorporate any other page elements you want by typing the HTML code. This is useful when you want something that is not already built into the Markdown syntax. For example, if I type `<strong> bold </strong> I’ll get bold . For a less trivial example, RMarkdown has built in functions for creating links to other webpages, but doesn’t support the option to open those in new tabs, so you’ll have to program links like that yourself.

If your HTML is appearing at text instead of running as code, remove any spaces before it.

Javascript Code Chunks

You can even build in Javascript code to carry out functions after particular events. Wrap your code in <script>...</script> and then you can indent your Javascript normally.

I will cover both HTML and Javascript coding more in the Advanced tutorial.

Themes

The default styling of the HTML document is not especially pretty but can be improved really quickly using the themes.

In your heading, replace

output: html_document
---

With

output: 
  html_document: 
    highlight: pygments
    theme: united
---

The spacing matters.

You can also get at all of these options through a GUI by clicking the little gear next to “Knit HTML” and poking around in ‘Output Options’. There’s an option in there to number the sections, which could potentially be useful.

  • theme controls the font and styling of everything over than the code. There are a couple of other optiosn and I like cosmo too.

  • highlight controls how the code chunks are colored, there are also a few other possible highlighting options but I don’t know them well.

Here are a couple of more commands that can be useful:

  • css:custom.css tells it to load a custom css file that’s in the same directory as the .Rmd file. These rules will get priority over theme styling. You could also use a relative path like /css/custom.css.

  • self_contained:false tells it not to go through this weird process of internalizing all of the images and libraries but you might want to keep it on if you’re emailing your html file to someone.

Finally you can also add a Table of Contents and Section Numbering, the steps are covered here.