Last updated: August 17, 2019. Feel free to read this, but it’s a legacy blog post right now and not very informative for those interested in learning to use R Markdown. You can read an update here.
I’ve been using LaTeX for document rendering for over five years. No one else in my department at the time used it, beyond my friend Joe (who introduced it to me). There was no pressure from my department to learn it, only a curiosity on my end for the benefits of it. The transition to LaTeX came with a concurrent transition to its sister package Beamer, which renders Powerpoint-styled presentations. Both have numerous advantages over their Microsoft equivalents.
However, I never particularly cared for Beamer. At least, I found LaTeX’s document preparation system more intuitive than Beamer’s slides preparation system. Using both will lead to proficiency, but Beamer markup remains ugly and a chore to write.
Look at it this way. Almost the entirety of a LaTeX document is the content itself whereas it seems half (if not more) of a Beamer document is markup. Take, for example, this sample code from a lecture slide for one of my classes.
That’s a lot of manual code for one little slide.
I’ve known about Markdown language (and Pandoc) as a substitute for straight Beamer. Markdown language is simple and elegant. Pandoc allows for Markdown to be translated to TeX, and ultimately a Beamer PDF. However, Pandoc is something of a chore to render. Look at all these extra commands one needs in a terminal to make even minimal changes (e.g. a simple theme, let alone a custom one) to a Pandoc call. I don’t have time for all that when a simple Cmd-R in Textmate (or F5 in Gedit’s LaTeX plugin) will do the same thing when the appropriate markup is included in the preamble of the document.
R Markdown is the best of both worlds. R Markdown allows for elegant Markdown code and simple means of stylizing and rendering the slides without a ton of additional commands in the terminal. It took a while to get something that was exactly what I wanted (since R Markdown has its own peculiarities), but I did and offer what follows as a guide for those looking to take advantage of R Markdown.
Understanding Your Markdown Document
R Markdown uses YAML for its metadata. It also does so in a manner that’s more efficient than Pandoc (or, at least, more intuitive for me). Consider my working example below.
--- title: An Example R Markdown Document subtitle: (A Subtitle Would Go Here if This Were a Class) author: Steven V. Miller date: fontsize: 10pt output: beamer_presentation: # keep_tex: true # toc: true slide_level: 3 includes: in_header: ~/Dropbox/teaching/clemson-beamer-header-simple.txt after_body: ~/Dropbox/teaching/table-of-contents.txt ---
Metadata is always at the top of a R Markdown document. I’ll explain some important YAML items below, assuming some items (e.g. title, subtitle, date, author, fontsize) are intuitive.
The output section designates how the Markdown language will be processed. You can insert
html_document if HTML is the desired output, though I’m assuming the preferred output here is a Beamer PDF.
beamer_presentation, enter a new line, hit the space bar four times and add miscellaneous options. In the working example above, I commented out two options. When
keep_tex is true, the compiling will also spit out a .tex file of the Markdown document. When
toc is true, a table of contents is rendered after the title frame. In my case, I don’t want a .tex output in addition to the PDF (unless I’m doing some debugging) and I like my table of contents after my slides. 1
The next option is an important one and it took me a while to figure out what exactly it was doing.
slide_level determines how many pound signs are required for Markdown to assume you are wanting a new slide. I think the default option is one, but this may be inefficient if you want clear sections and subsections in your presentation. If
slide_level is three, then Markdown output like this…
…will look like this standard TeX/Beamer markup.
Since this is how I’m used to handling Beamer (and I like occasional subsections in my slides and in the table of contents), I set
slide_level to three.
Next, you can use
includes:) to determine what additional packages and style changes you want to include in what would otherwise be the preamble of your Beamer document. This is where you can get creative with stylizing a theme how you want. I also thought it mandatory because Markdown does some things with Beamer that I think are odd (e.g. giving a section title its own slide). Here’s my standard style file, for your consideration.
Most of these are cosmetic fixes (i.e. representing school colors in my presentations, which you are free to change), but some commands are quite useful. The last two commands in the above code reduce some of R Markdown’s odd vertical spacing. The four lines above that suppress R Markdown’s proclivity to create new slides that are just the section titles.
after_body is an optional command that will include whatever you want as slides material after what is otherwise the last slide of your document. Since I like table of contents after the last slide, I have simple .txt file with the following Beamer markup.
## Compiling Your Markdown Document
If you’re using Rstudio, compiling the R Markdown document is as simple as clicking a few buttons in the script window.
However, I tend to not like using GUIs, even if Rstudio is quite useful. I do love automated scripts, though, especially R scripts in which I don’t have to specify a working directory. Toward that end, I wrote a simple script that you can treat as executable (assuming you’re on a Linux or Mac machine) to automatically compile your Markdown documents.
This process assumes you have just one .Rmd file per directory, which should not be a drastic change for LaTeX users. Given LaTeX’s proclivity to create log files and additional auxiliary files with every compile, LaTeX users (like me) tend to get in the habit of having one directory for each document.
Save that script with a .R extension and allow your Linux or Mac operating system to treat it as executable. You should be good to go after that.
An Example R Markdown Document
Here’s a sample document I created in Markdown for illustration purposes. This is the output from compiling it with my R script.
This was something I started doing in job market talks in order to field questions back to particular slides more easily. ↩