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
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
./_episodes. It is possible to have Markdown files in
don’t have their counterparts in
./_episodes_rmd as long as their names are
The required preamble
Each episode needs to start with a chunk that includes:
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
01- but it should be adjusted to the correct episode number. We can’t use
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
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.,
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: