Using RMarkdown with the new lesson template

This post originally appeared on the Software Carpentry website.

Our lesson template is getting a face-lift. Actually, it is a lot more than that: all the internal mechanics are also affected.

What’s new with the template?

The lesson maintainers have developed a new template that comes with features that have been repeatedly requested such as an easy way to navigate among episodes within a lesson: there are now “previous” and “next” arrows in each episode.

This new template does not require having to use pandoc. Currently, the lessons are written in Markdown, and converted into HTML by our lesson maintainers using a wonderful piece of software called pandoc. Instead, the new template uses jekyll to take care of the conversion from Markdown into HTML. Lesson maintainers will still need to have jekyll installed to check that the website gets generated correctly, but the conversion from Markdown to HTML for our online lessons will be handled directly by jekyll on the GitHub servers. This means less work for our lesson maintainers and contributors, as they will only to change to the markdown files. It also means that we will not have to put the generated HTML files in the repository, which removes another common source of error and frustration.

What does it mean for the lessons written in RMarkdown?

For the lessons covering R, we still need to keep in the repository both the RMarkdown files and the Markdown files. We write our lessons in RMarkdown to ensure that all the code included in the lessons works correctly. Because of the organization of the files with the new template, a few details had to be adjusted but for the most part, writing lessons in RMarkdown with the new template should not be too different from the current template.

Contributors to the lessons should edit the Rmd files, and the lesson maintainers will run make lesson-md to generate the corresponding Markdown files using knitr, before pushing these changes to the lesson repository.

The Rmd files live in the ./_episodes_rmd folder, and their respective Markdown files live in ./_episodes. The Makefile takes care of calling knitr::knit() on each Rmd files in ./_episodes_rmd and writing the output in ./_episodes. It is possible to have Markdown files in ./_episodes that don’t have their counterparts in ./_episodes_rmd as long as their names are different.

The required preamble

Each episode needs to start with a chunk that includes:

source("../bin/chunk-options.R")
knitr_fig_path("01-")

The first line ensures that all the knitr options required to make the output compatible with the template are set correctly.

The second line adds the episode number in front of each figure file. Here I used 01- but it should be adjusted to the correct episode number. We can’t use the knitr function opts_chunk$set(fig.path="01-") here as it would place the figures in a folder that wouldn’t make them accessible to the template by overwriting the global definition of this variable. As currently configured, all figures generated by code included in the episodes will be prefixed with rmd-, such that figures generated by the first episodes will all start with rmd-01-, making it easy to identify the origin of each figure in the ./fig folder.

Data files

If the code in one of your episodes relies on data files (or other files), they will need to be placed in a sub-folder (e.g., ./_episodes_rmd/data). This allows contributors to work interactively with each episode, and the code included in the episode looks like how we ask learners to get setup.

The new template in the wild

If you want to see examples of the new template in action, you can check out:

• the rendered lesson-example episode about using RMarkdown and its source
• the r-novice-gapminder and its source that I converted to the new template